Repository navigation
feat(examples): OrcaRouter recipe on traceai-openai (TH-8307) - #240
Merged
Merged
Conversation
Adds python/examples/orcarouter/: the official openai SDK pointed at OrcaRouter's OpenAI-compatible base URL https://api.orcarouter.ai/v1, traced by the existing traceai-openai instrumentor. No provider package. - ORCAROUTER_API_KEY and a model (ORCAROUTER_MODEL or --model) are required; main() exits 2 before tracing on missing values or a refused ORCAROUTER_BASE_URL. URLs are validated, never rewritten. - On api.orcarouter.ai: https only, exactly /v1 or /v1/ (the bare root also serves other protocol surfaces), no query or fragment. Everywhere: whitespace/control characters, non-ASCII or malformed IDNA hosts and URL credentials are refused. Customer proxies and loopback allowed. - Model resolution pinned: a successful non-streamed span records the model id the gateway returns (fixture: orcarouter/auto resolved to a dated upstream id) while gen_ai.request.parameters keeps the requested id; streamed and failed spans have no gen_ai.request.model. - Fallback chains (extra_body.models) reach the gateway unchanged and are not recorded in gen_ai.request.parameters (pinned, documented). - Chat Completions output.value is the assistant text; extra response metadata is not exported; FI_HIDE_INPUTS/FI_HIDE_OUTPUTS with controls. - Key only on the OpenAI client; Future AGI keys only on the tracer. - Loopback only: MockTransport at the documented host, a local OpenAI-shaped fake, the shared harness receiver and a socket guard with a negative control. approved: Nikhil 2026-10-03 blanket Refs: TH-8307
…host checks - README: states that OrcaRouter documents no trace export (its Observability page offers an OpenMetrics workspace scrape, a request-id header and console logs; checked 2026-10-06), so the recipe traces on the client and imports nothing from OrcaRouter. - README: gateway errors (wrong or non-OrcaRouter key, unfunded wallet, rate limits) are OrcaRouter errors recorded as ERROR spans, not Future AGI ingest failures; orcarouter/auto needs a funded wallet (403 insufficient_user_quota), cited. - README: model resolution attributed only to orcarouter/auto; the output-metadata sentence narrowed to unrecognised top-level fields; FI_HIDE_LLM_INVOCATION_PARAMETERS leaves streamed and failed spans with no model at all (new test, with control). - check_base_url refuses backslashes, percent-encoding and empty labels in any host before tracing (new refusal cases). - Tests: temperature control beside the fallback-chain absence check; the content scan reads only .py/.md/.txt outside __pycache__; the internal-name word list is removed (generic id and key checks stay). approved: Nikhil 2026-10-03 blanket Refs: TH-8307
…or's The README sourced a claim from a third-party observability vendor's docs. Future AGI READMEs should not send readers there; the claim now cites OrcaRouter's Auto Router and Errors pages. Docs only (plus the README contract test where it pinned the old link). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… provider/model fix The recipe pinned traceai-openai 0.1.10 behaviour: gen_ai.provider.name is always "openai" and streamed/failed spans carry no gen_ai.request.model. #249 labels known vendor hosts and records the requested model, so these pins would break whichever PR merged second. Accept both behaviours (and the related Responses/embedding output changes where this recipe checks them), and say in the README which version does what. Passes against published traceAI-openai 0.1.10 and against #249. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
setup_tracing() passed project_name or "orcarouter-example" to register(), so the default was always truthy and FI_PROJECT_NAME was never read: `python src/app.py` always exported to orcarouter-example. The Anannas recipe reads FI_PROJECT_NAME with its name as the default; do the same here. An explicit setup_tracing() argument still wins, and an unset or empty FI_PROJECT_NAME keeps orcarouter-example (never register()'s generic default). - README: FI_PROJECT_NAME in the Configure table and the Run section; the Code snippet reads it the same way as src/app.py. - Tests: setup_tracing() default / empty / env / explicit cases; the guarded app.py subprocess runs with FI_PROJECT_NAME unset and set; the README contract checks the new row and snippet. Passes against repository source, published traceAI-openai 0.1.10 and #249. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Code <noreply@anthropic.com>
Keep endpoint, model and auth guidance factual. Add exact-head offline recipe CI for repository source, the SDK floor and published packages. Co-Authored-By: Claude Code <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add the OrcaRouter OpenAI-compatible recipe under
python/examples/orcarouterusing the existingtraceAI-openaiinstrumentor. No new provider-specific tracing package or runtime patch is needed.https://api.orcarouter.ai/v1,ORCAROUTER_API_KEY, and a model fromGET /v1/models, including provider-prefixed IDs such asopenai/gpt-4o-miniororcarouter/auto./v1/chat/completions. Keep native Anthropic/Gemini surfaces separate from this recipe.stream_options={"include_usage": True}for the final usage chunk; the CLI leaves this option unset by default.Implementation
Register the Observe provider, instrument before constructing the client, keep vendor credentials on that client, and flush tracing in
finally. Keep model and token fields conditional on what the API returns. The request/span contracts follow the existing Novita, CometAPI, and Z.ai recipe family.Merge current
devinto the branch and add an exact-head recipe CI matrix for repository source, the OpenAI SDK floor, and the pinned published packages. The workflow uses isolated HTTP fixtures and loopback network guards.Official API references
🤖 Generated with Claude Code