Evaluate a DSPy tools adapter (dspy.Tool / ReAct ↔ SelectableItem)

Start by reading adapters/crewai.py or smolagents.py, then inspect #454 and DSPy's current Tool API documentation. Run the proposed scratch spike without adding dependencies, evaluating schema mapping, routed shortlists, optimizer interaction, and demand evidence. Done means a written recommendation with the manual 50+ tool transcript and either a follow-up adapter issue or a recorded no-integration decision.

Summary

Investigate whether a DSPy adapter fits the established adapter pattern: converting dspy.Tool definitions used by DSPy's ReAct-style agents into SelectableItem catalogs (so large DSPy tool sets get deterministic shortlisting), and assessing whether DSPy's optimizer-centric workflow creates a meaningful integration seam beyond tool conversion. Framed as an investigation: validate fit and demand before committing adapter code.

Why this matters

The adapter surface is the project's main distribution mechanism, and DSPy is a widely used Python agent-building framework with a tool abstraction and ReAct agents — structurally the same shape as the CrewAI/smolagents/Agno adapters already shipped. An evaluation closes the gap deliberately (adapter, guide-only, or documented no) instead of leaving the question open, and follows the precedent of evaluation-first integration issues in the backlog.

Current evidence

• No DSPy references exist anywhere in the repo (grep across src/, docs/, README: zero hits), while 12 framework integrations ship adapters or guides (src/contextweaver/adapters/, docs/integration_*.md).
• The conversion target is well-trodden: crewai.py, smolagents.py, agno.py adapters all map framework tool objects → SelectableItem (name/description/args schema), and #454 (open) plans a shared conversion toolkit these would refactor onto.
• Precedent for evaluation-first framing: newly filed #549 ("Evaluate a Strands Agents adapter") — this issue follows the same template for DSPy; the adapter acceptance/lifecycle policy candidate (ISSUE 17) defines the criteria such evaluations should apply.

External context

DSPy (Stanford NLP lineage, actively maintained) exposes dspy.Tool and ReAct modules whose tool lists are passed whole to the model — the exact pattern (many tools → full prompt) contextweaver's routing addresses. Its differentiating feature, prompt optimization, is orthogonal to context compilation, which is precisely what the investigation should confirm or refute.

Proposed implementation

1. Spike: map dspy.Tool fields onto SelectableItem (verify args-schema availability and stability across recent DSPy versions); prototype from_dspy_tools(tools) -> list[SelectableItem] and a routed-shortlist-back-to-ReAct loop in a scratch example.
2. Assess the seam honestly: does routing fit inside DSPy's compiled programs, or only at the outer agent loop? Does DSPy's optimizer interact badly with a changing tool subset per query?
3. Check demand signals (DSPy issue tracker requests for tool-scaling, community integrations list).
4. Decide per the adapter lifecycle policy (ISSUE 17): full adapter under extras/adapters, docs-guide-only, or documented decision not to integrate — and file the follow-up accordingly.

AI-agent execution notes

• Inspect first: adapters/crewai.py or smolagents.py (the closest patterns), #454's shared-toolkit direction (don't pre-empt it with a 13th bespoke converter if it's landing), DSPy's current Tool API docs.
• Pin the DSPy version evaluated; note API stability observations in the writeup (DSPy has a fast release cadence).
• Do not add DSPy to any dependency group during the investigation; the spike lives in a scratch branch/gist, not the repo.

Acceptance criteria

• A written evaluation answers: mapping feasibility, seam quality, optimizer interaction, demand evidence, and a recommendation with rationale.
• If "adapter": a follow-up implementation issue exists referencing #454's toolkit. If "no": the decision is recorded where future contributors will find it (ecosystem docs or AGENTS notes).

Test plan

Investigation only; the spike includes a manual end-to-end run (DSPy ReAct agent over a 50+ tool catalog with routed shortlists) whose transcript/numbers appear in the writeup.

Documentation plan

Outcome recorded in the issue + ecosystem docs if guide-only; no docs change for a "no" beyond the decision note.

Migration and compatibility notes

Not expected to require migration.

Risks and tradeoffs

DSPy API churn could obsolete findings quickly (pin and date the evaluation); a 13th integration grows the maintenance surface ISSUE 17 exists to control — the evaluation explicitly applies that policy rather than defaulting to "ship it".

Suggested labels

investigation, integrations, ecosystem