feat(reflect): add multi-step reasoning with query decomposition

[bjornslib]

Summary

• decompose() tool for the reflect agent to break complex queries into 2-4 focused sub-questions
• Budget-gated: only available for MID and HIGH budget queries (no impact on LOW)
• ReasoningStep/ReasoningChain models for structured reasoning traces
• include_reasoning_chain parameter on reflect API to expose the chain
• Fix Gemini tool schema compatibility (remove additionalProperties, minItems, maxItems)
• Fix reflect ValueError handler to pass actual error messages

Motivation

Complex queries that span multiple topics or require comparative analysis benefit from structured decomposition. Rather than building a separate multi-step system, this extends the existing reflect agent's agentic loop with a new decompose() tool that the LLM can choose to use when appropriate.

Modified files (all in reflect subsystem)

• engine/reflect/tools_schema.py — TOOL_DECOMPOSE definition, budget parameter on get_reflect_tools()
• engine/reflect/tools.py — tool_decompose() handler
• engine/reflect/prompts.py — MID/HIGH budget guidance for decomposition
• engine/reflect/agent.py — Dispatch + ReasoningChain construction
• engine/reflect/models.py — ReasoningStep/ReasoningChain dataclasses
• engine/response_models.py — reasoning_chain field on ReflectResult
• engine/memory_engine.py — Chain serialization
• api/http.py — Request/response fields for reasoning chain

Test plan

• Reflect with budget=low does NOT offer decompose tool
• Reflect with budget=mid/high includes decompose in available tools
• Complex query triggers decomposition and returns reasoning_chain when requested
• Simple queries still work without decomposition
• Gemini provider works with updated tool schemas
• Backward compatible: no changes when include_reasoning_chain=false (default)

🤖 Generated with Claude Code

[bjornslib]

I'm in the process of building out additional functions to support the "Second Brain" concepts discussed by Nate B. Jones. I've seen the automated tests fail?

[nicoloboschi]

I really like this idea but I think a better approach is to systematically split into parallel sub reflect agent and have a coordinator, instead of just decomposing and hoping the model will combine all researches together.

I think it's a much harder work but it's probably worth it.

Are you interesting in moving this PR to that approach?
if you don't have bandwidth it's fine