Skip to content

feat(examples): Doubleword recipe on traceai-openai (TH-8309) - #242

Merged
nik13 merged 9 commits into
devfrom
feat/th-8309-doubleword
Oct 28, 2026
Merged

nik13 merged 9 commits into
devfrom
feat/th-8309-doubleword

Conversation

@nik13

@nik13 nik13 commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Add the Doubleword OpenAI-compatible recipe under python/examples/doubleword using the existing traceAI-openai instrumentor. No new provider-specific tracing package or runtime patch is needed.

  • Use https://api.doubleword.ai/v1, DOUBLEWORD_API_KEY, and DOUBLEWORD_MODEL. The OpenAI client sends bearer authentication and makes synchronous Chat Completions requests.
  • Select an exact model ID, including its organization prefix, from the model catalog or client.models.list(). Dedicated deployments use organization-specific names supplied by Doubleword.
  • Distinguish synchronous Chat Completions from async Responses API requests (service_tier="flex"), Autobatcher, Batch, and dedicated deployment provisioning. Describe current shared-capacity concurrency limits rather than a stale production-suitability quote.
  • Preserve streaming accumulation, conditional token usage, embeddings fixture contracts, privacy controls, URL checks, SDK errors, and vendor/collector key separation.
  • Pin exact status descriptions and qualified exception types across current and published fi-core behavior.

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 dev into 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

nik13 added 2 commits October 5, 2026 23:44
Adds python/examples/doubleword/: the official openai SDK pointed at
Doubleword's OpenAI-compatible base URL https://api.doubleword.ai/v1,
traced by the existing traceai-openai instrumentor. No provider package.

- DOUBLEWORD_API_KEY and a model (DOUBLEWORD_MODEL or --model) are
  required; main() exits 2 before tracing on missing values or a refused
  DOUBLEWORD_BASE_URL. URLs are validated, never rewritten.
- On api.doubleword.ai: https only, exactly /v1 or /v1/, no query or
  fragment delimiter; the Batch API (/batch, /v1/batch...), the
  Anthropic Messages API (/messages, /v1/messages) and endpoint paths are
  refused with specific messages. Everywhere: whitespace/control
  characters, non-ASCII or malformed hosts and URL credentials are
  refused. Customer proxies and loopback allowed.
- Realtime and the async tier: service_tier="flex" (a native SDK
  parameter, branched on the installed SDK version) reaches the request
  body and gen_ai.request.parameters.
- Pins current traceai-openai behaviour: a successful non-streamed span
  records the model id the provider returns, the requested id stays in
  gen_ai.request.parameters; streamed and failed spans omit the model.
- Embeddings: the span exports the raw response JSON (vectors included)
  under embedding.embeddings, which FI_HIDE_EMBEDDING_VECTORS does not
  mask; pinned and documented.
- Chat Completions output.value is the assistant text; FI_HIDE_INPUTS /
  FI_HIDE_OUTPUTS with controls. The recipe keeps the SDK's default
  retries; error tests disable them on the test client.
- 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 loopback control.

approved: Nikhil 2026-10-03 blanket
Refs: TH-8309
- service_tier test pins the runtime claim (value in body and span
  parameters) and no longer asserts version-specific type annotations,
  which broke on 1.x releases between the tested pins.
- Subprocess PYTHONPATH lists the instrumentation roots before the SDK
  site-packages, so the child imports the same instrumentor as the
  parent even when published wheels are installed.
- The internal-id scan reads only .py/.md/.txt files outside
  __pycache__ and test-run directories.
- Proxy host names may contain underscores inside a label (Compose
  service names); label edges and the vendor-host rules are unchanged.
- README: a non-streamed response with empty content exports no
  output.value; service_tier wording matches the test.

approved: Nikhil 2026-10-03 blanket
Refs: TH-8309
@nik13
nik13 requested a review from NVJKKartik October 10, 2026 08:42
…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
Doubleword's API reference (llms.txt). Docs only (plus the README contract test where it pinned the old link).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
nik13 and others added 6 commits October 11, 2026 21:32
… 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 "doubleword-example" to
register(), so the default was always truthy and FI_PROJECT_NAME was
never read: `python src/app.py` always exported to doubleword-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 doubleword-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>
Assert exact status descriptions and qualified exception types across
fi-core versions, including the newer redundant-type-prefix cleanup.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@nik13
nik13 merged commit 0f154a8 into dev Oct 28, 2026
23 checks passed
@nik13
nik13 deleted the feat/th-8309-doubleword branch October 28, 2026 05:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant