Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Cross-protocol semantic input rejections raise `molto.types.exceptions.Unsupport

Native same-protocol routes preserve request dictionaries, including unknown properties, nested extensions, and explicit nulls, without validating them against Molto's protocol models. The SDK and upstream provider own request validation. Explicit `extra_body` overrides take precedence over fields supplied in `body`. Molto still enforces the destination restriction on its own [Anthropic search metadata extension](web-search.md#preserving-anthropic-search-history).

Native coordinators select streaming only when `body["stream"]` is the boolean `True`. Other values are forwarded unchanged for SDK and provider validation; values such as `1` or `"false"` do not select Molto's streaming path.
Native coordinators select streaming when `body["stream"]` is truthy, the same rule the OpenAI and Anthropic SDKs use (`stream=stream or False`), so Molto always expects the response type the SDK returns. The value is forwarded unchanged for provider validation; `1` or `"false"` therefore streams, and a provider that rejects the value raises its own error.

Each coordinator accepts a dictionary or its corresponding Molto request model. Serialize caller-defined Pydantic models to dictionaries before passing them to Molto. On native routes, Molto request models use their normal `model_dump()` behavior, which omits unset and `None`-valued fields. Model serialization can discard unknown fields, including extras accepted through `extra="allow"`; use a dictionary to preserve unknown fields and explicit nulls. SDK models nested in native request dictionaries retain their SDK serialization behavior.

Expand Down Expand Up @@ -74,6 +74,10 @@ Use the same protocol for the method and `endpoint` to select native passthrough

`Molto` owns its shared `httpx.AsyncClient`. A returned stream releases its response when its context exits, including after early termination. Closing `Molto`, either with `async with` or `await molto.aclose()`, closes the shared HTTP client.

## Observability

Molto emits one OpenTelemetry span per coordinator call, using only `opentelemetry-api`; the application configures export. The [observability contract](observability.md) defines the span, its attributes and events, and its content policy.

## Routing

Four independent choices define a route:
Expand Down
187 changes: 187 additions & 0 deletions docs/observability.md

Large diffs are not rendered by default.

9 changes: 9 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -79,11 +79,17 @@ classifiers = [
# The openai floor is a hard import requirement, not a preference;
# the ceilings are releases where tests start failing.
# Re-derive from the suite before widening either bound; see AGENTS.md, "Dependency Versions".
# opentelemetry-api: the full suite passes on 1.36.0 with the matching SDK and httpx
# instrumentor; 1.28.0 (pydantic-ai-slim's floor) fails only tests of the test-only
# instrumentor's API. The <1.46 ceiling stops just above 1.45.2, the newest
# release the suite passes on; each SDK release requires the matching API version, so
# re-derive it with the suite when a new release appears.
# The test extra pins the exact versions the suite is developed against.
dependencies = [
"anthropic>=0.119.0,<0.124",
"loguru~=0.7",
"openai>=2.45.0,<3.2",
"opentelemetry-api>=1.36.0,<1.46",
"orjson~=3.11",
"pydantic-ai-slim[retries]~=1.104.0",
"pydantic-settings~=2.13.1",
Expand All @@ -100,6 +106,9 @@ test = [
"anthropic==0.121.0",
"fastapi[standard]==0.135.4",
"openai==2.53.0",
"opentelemetry-api==1.45.2",
"opentelemetry-instrumentation-httpx==0.66b2",
"opentelemetry-sdk==1.45.2",
"pytest==8.4.2",
"pytest-asyncio==1.4.0",
"pytest-cov==7.1.0",
Expand Down
4 changes: 4 additions & 0 deletions python/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,10 @@ Adapters and upstream clients do not depend on each other. Protocol-specific coo

Upstream clients normalize recognized SDK failures as `APIException`; downstream adapters project them into their SDK namespace. Both native and translated routes use this pipeline for streaming and non-streaming requests. See [Errors](../docs/errors.md) for recognition rules, status mappings, and special cases.

## Instrumentation

The coordinator owns spans: only `core.py` creates and ends them, while adapters, normalizers, and upstream clients stay telemetry-free. Telemetry never influences routing or translation. `_traced` in `core.py` starts one span per coordinator call, and `MoltoStream` ends it for streams. The coordinators pass upstream output through `observe` and a `SpanRecorder` (`utils/telemetry.py`), which only read it to add end attributes and the `molto.first_token` event. `record_safely` logs and drops a recording failure, so telemetry never fails a call. The [observability contract](../docs/observability.md) defines the span and its rules.

## Orchestration facade and coordinators

`Molto` is expected to expose one coordinator method per downstream protocol:
Expand Down
Loading
Loading