Skip to content

Provider Updates

This page documents how to keep Agent aligned when provider APIs evolve.

Files likely to change

  • src/doc_processing_toolkit/agent/core.py
  • src/doc_processing_toolkit/agent/parameter_mapping.py
  • src/doc_processing_toolkit/agent/config.py
  • src/doc_processing_toolkit/agent/result.py
  • src/doc_processing_toolkit/mcp_servers/agent_factory.py

Common update scenarios

1) New provider parameter added

  • Decide whether parameter is universal or provider-specific.
  • Update mapping and validation in parameter_mapping.py.
  • Add constructor/config wiring only when exposed in Agent API.
  • Verify dynamic function signature filtering still passes supported kwargs.

2) Parameter removed or renamed

  • Remove or remap target fields in mapping tables.
  • Preserve backward-compatible behavior where practical.
  • Update tests for expected pass-through/filtering behavior.

3) Return payload shape changed

  • Update Agent._convert_result(...) in agent/core.py.
  • Extend AgentResult dataclass if new output fields are needed.

4) New provider added

  • Add provider detection fallback in _detect_provider(...) and model metadata.
  • Add provider call bindings in _get_function_calling_func and _get_structured_output_func.
  • Extend client initialization paths in utils.py.
  • Add integration/e2e coverage for function-calling and structured-output paths.

5) Provider SDK ships a breaking major version

A provider SDK can move or delete its import surface independently of the model API. The pattern the toolkit uses for this (established for fireworks-ai 1.x) is:

  • Guard the import in src/doc_processing_toolkit/__init__.py with a dual path: try the new surface first, fall back to the legacy one, and set an availability flag plus an era marker (FIREWORKS_SDK_AVAILABLE / FIREWORKS_SDK_MAJOR). When the import surface did not move and only keywords did (anthropic 1.x), the era marker alone is enough (ANTHROPIC_SDK_MAJOR).
  • Re-export the SDK classes from the package root and import them from there in utils.py and the provider module, so the import path is defined in exactly one place.
  • Gate era-specific constructor kwargs and request parameters on the era marker rather than branching on a version string or catching TypeError.
  • Pin the dependency to the tested range in setup.py and requirements.txt. An unpinned SDK is what allows a breaking major to land silently on the next fresh build.
  • Add unit coverage that fakes each era through sys.modules so both paths are exercised without installing both SDKs.
  • Bind every keyword the provider passes against the installed SDK's own method signatures (tests/unit/test_anthropic_sdk_lines.py). Unit fakes accept any keyword, so without this a keyword the SDK removed is found only by a live call.
  • Check the HTTP layer too. openai 3.x and anthropic 1.x moved from httpx to httpx2: the exception classes, the timeout type and the TLS trust store all changed with it.

Note that an import guard that fails degrades quietly: the provider is marked unavailable at import time and calls fail later with an unrelated-looking client error. Check the boot-time warning when a provider unexpectedly stops working.

See Providers for the current Fireworks state.

6) Model retired, added, or repriced upstream

Model availability and pricing live entirely in data/model_information.json, so this class of change is a data edit — no Python change is normally required.

  • Retired upstream: verify the model actually 404s against the live API before removing it, then delete its pricing, limits and descriptions entries together. Grep the repo for the model ID afterwards: test fixtures and MODEL_OVERRIDE_* examples in the test READMEs tend to pin specific cheap models, and a retired default silently breaks those runs.
  • Added: add all three blocks, and set the capability flags from vendor documentation rather than copying a sibling model. Capabilities do not inherit along a version number — a newer model can drop support (gemini-3.7-flash removed the minimal thinking level that every earlier Gemini 3.x Flash accepted).
  • Repriced: promotional and tiered prices both belong in the registry; record the current-effective price, and keep long-context tier thresholds alongside the base rate.

Enumerated capability tables in these docs — notably the thinking-level and reasoning-effort tables in Thinking — are hand-maintained and do not regenerate from the registry. Update them in the same change, or they drift.

Validation checklist

  • Unit tests: mapping/config/agent behavior
  • Integration tests: provider function and structured calls
  • E2E tests: full Agent orchestration flows

Suggested order:

  1. tests/unit/run_tests.py
  2. tests/integration/run_tests.py --file <target_file>
  3. tests/e2e/run_tests.py --file <target_file>

For full validation use tests/run_all_tests.py.

Notes

  • Dynamic parameter filtering in Agent reduces breakage risk for additive provider changes.
  • Prefer targeted updates and focused tests over broad refactors.