Skip to content

docs: surface tracing and deep research in the README #156

Description

@cyfyifanchen

Problem

Raven now has two user-facing capabilities that are not visible enough in README.md:

  • Observability tracing: raven tracing opens the bundled dashboard for captured LLM/tool/memory spans, and the TUI exposes /tracing.
  • Deep research: raven deep-research configures the MiroThinker-backed deep_research tool, which can run longer research tasks when configured.

The README still leads with memory, self-improving skills, Agent Templates, proactivity, and self-evolution. Those are still correct, but the repo homepage does not show tracing or deep research in the quick capability scan, the command table, or the status/architecture surfaces.

Evidence

  • raven/cli/tracing_commands.py registers the top-level raven tracing command and describes the local dashboard under raven/tracing/viewer/.
  • ui-tui/src/app/slash/commands/ops.ts exposes /tracing as a TUI slash command.
  • raven/config/raven.py has tracing enabled by default and documents RAVEN_TRACING=0 plus raven tracing / /tracing.
  • raven/cli/deep_research_commands.py registers raven deep-research enable|get|reset for MiroThinker deep research configuration.
  • raven/agent/loop/main.py wires configured deep research into the agent loop as the deep_research tool.

Suggested README updates

  • Add tracing and deep research to the early capability list, likely under What You Can Do in 2 Minutes, Why Raven, Useful Commands, and Status.
  • Consider adding a short observability row to the comparison table, e.g. captured spans for LLM/tool/memory/subagent activity vs opaque logs.
  • Add raven tracing and raven deep-research enable|get|reset to Useful Commands.
  • Clarify deep research is opt-in and provider/API-key backed, so readers do not assume it is always enabled or free.
  • Mirror the key updates in README.zh-CN.md if the English README changes.

Acceptance criteria

  • README.md makes tracing and deep research visible without requiring readers to inspect source code.
  • The commands shown in README match the current CLI: raven tracing, /tracing, and raven deep-research enable|get|reset.
  • The copy preserves the current positioning: Raven is still a self-improving agent harness, with tracing and deep research framed as additional harness capabilities.
  • README.zh-CN.md stays consistent with the English README where applicable.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions