feat(change): add tool router for providers #302

Closed
opened 2026-02-22 23:41:06 +00:00 by freemo · 1 comment
Owner

Metadata

  • Commit: feat(change): add tool router for providers
  • Branch: feature/m3-tool-router

Subtasks

  • Implement ToolCallRouter for OpenAI/Anthropic/LangChain tool schemas with deterministic IDs.
  • Add mapping for tool/validation names and argument schemas based on Tool Registry metadata.
  • Add tool-call result normalization to match ToolInvocation schema.
  • Add provider-specific handling for streaming tool calls (accumulate args + finalize when complete).
  • Ensure validation tools are surfaced with tool_type=validation in provider payloads.
  • Normalize tool schemas to provider limits (field pruning, max description length) with explicit warnings.
  • Add stable tool-call ID generation (plan_id + tool_name + sequence) and include in ToolInvocation metadata.
  • Add error mapping for provider tool-call failures (timeout, schema error, tool not found) into ToolInvocation.error.
  • Add provider metadata capture (model name, provider id, latency) for each tool call.
  • Add docs/reference/tool_router.md with provider-specific mappings.
  • Tests (Behave): Add features/tool_router.feature for schema mapping.
  • Tests (Robot): Add robot/tool_router.robot for routing smoke tests.
  • Tests (ASV): Add benchmarks/tool_router_bench.py for routing performance.
  • Verify coverage >=97% via nox -s coverage_report. If coverage is <97% then review the current unit test coverage report at build/coverage.xml and use it to write new Behave based unit tests to improve coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun nox -s coverage_report to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.
  • Run nox (all default sessions, including benchmark), fix any errors if needed ensuring nox passes across entire code base, do not ignore any failure even if it seems unrelated to this commit, fix it.

Section: ### Section 5: Actors, Skills & Tool Execution [WORKSTREAM C - Aditya Lead]
Status: Completed

## Metadata - **Commit**: `feat(change): add tool router for providers` - **Branch**: `feature/m3-tool-router` ## Subtasks - [x] Implement ToolCallRouter for OpenAI/Anthropic/LangChain tool schemas with deterministic IDs. - [x] Add mapping for tool/validation names and argument schemas based on Tool Registry metadata. - [x] Add tool-call result normalization to match ToolInvocation schema. - [x] Add provider-specific handling for streaming tool calls (accumulate args + finalize when complete). - [x] Ensure validation tools are surfaced with `tool_type=validation` in provider payloads. - [x] Normalize tool schemas to provider limits (field pruning, max description length) with explicit warnings. - [x] Add stable tool-call ID generation (plan_id + tool_name + sequence) and include in ToolInvocation metadata. - [x] Add error mapping for provider tool-call failures (timeout, schema error, tool not found) into ToolInvocation.error. - [x] Add provider metadata capture (model name, provider id, latency) for each tool call. - [x] Add `docs/reference/tool_router.md` with provider-specific mappings. - [x] Tests (Behave): Add `features/tool_router.feature` for schema mapping. - [x] Tests (Robot): Add `robot/tool_router.robot` for routing smoke tests. - [x] Tests (ASV): Add `benchmarks/tool_router_bench.py` for routing performance. - [x] Verify coverage >=97% via `nox -s coverage_report`. If coverage is <97% then review the current unit test coverage report at `build/coverage.xml` and use it to write new Behave based unit tests to improve coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `nox -s coverage_report` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. - [x] Run `nox` (all default sessions, including benchmark), fix any errors if needed ensuring nox passes across **entire** code base, do not ignore any failure even if it seems unrelated to this commit, fix it. **Section**: ### Section 5: Actors, Skills & Tool Execution [WORKSTREAM C - Aditya Lead] **Status**: Completed
freemo added this to the v3.1.0 milestone 2026-02-22 23:41:06 +00:00
freemo self-assigned this 2026-02-22 23:41:06 +00:00
Author
Owner

Implementation Notes — C5.router: Tool Call Router for LLM Providers

2026-02-20: C5.router Complete - Tool Call Router for LLM Providers [Jeff]

  • Created router.py (~890 lines) — ToolCallRouter translating between LLM provider tool call formats and internal ToolRunner: provider format detection, normalization, deterministic ID generation, error classification, schema adaptation, batch routing, streaming support.
  • Key discovery: ToolRunner.execute() catches handler exceptions internally and returns ToolResult(success=False) rather than raising, so streaming produces COMPLETE + failed result (not ERROR update) for tool failures.
  • Key discovery: Pyright strict mode requires all Pydantic model fields (even those with defaults via Field(default=...)) to be explicitly passed in constructor calls.
  • Key discovery: Behave step name collision with existing coverage_boost_extra_steps.py; renamed to avoid AmbiguousStep error.

(Migrated from docs/implementation-notes.md)

## Implementation Notes — C5.router: Tool Call Router for LLM Providers **2026-02-20**: C5.router Complete - Tool Call Router for LLM Providers [Jeff] - Created `router.py` (~890 lines) — `ToolCallRouter` translating between LLM provider tool call formats and internal `ToolRunner`: provider format detection, normalization, deterministic ID generation, error classification, schema adaptation, batch routing, streaming support. - Key discovery: `ToolRunner.execute()` catches handler exceptions internally and returns `ToolResult(success=False)` rather than raising, so streaming produces COMPLETE + failed result (not ERROR update) for tool failures. - Key discovery: Pyright strict mode requires all Pydantic model fields (even those with defaults via `Field(default=...)`) to be explicitly passed in constructor calls. - Key discovery: Behave step name collision with existing `coverage_boost_extra_steps.py`; renamed to avoid `AmbiguousStep` error. *(Migrated from `docs/implementation-notes.md`)*
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#302
No description provided.