OSYRA SDKs overview

OSYRA ships two distinct SDK families. They solve different problems, talk to different parts of the OSYRA control plane, and you choose between them by the job you are doing — not by language preference:

1. Gateway SDKs — OpenAI-compatible llm clients that route your model calls through the OSYRA control plane (model broker, AP00006). For the verified Chat Completions, Embeddings, and Models subset, change one import and keep the OpenAI-shaped request; enabled workspace controls add routing, policy, cache, PII, usage, and evidence behavior. Available in Python and Go.
2. OME / Verified-Memory SDKs — Python and TypeScript pre-release packages whose offline verification surfaces can check trusted OME evidence locally. Their customer network path for memory write/read is still pending.

The public contract is no fabricated data. Gateway methods either use the real Edge route or fail loudly. For OME, a protocol implementation is not described as product availability: only offline verification is presented as runnable until the real Edge acceptance lane passes.

Family 1 — Gateway SDKs (OpenAI-compatible llm access)

Use these when you want model access — chat completions, embeddings, model listing — routed through OSYRA instead of calling a provider directly.

The gateway SDKs are a source-compatible client for the verified OpenAI-shaped surface. You change one import line and keep supported request fields; calls then flow through Osyra Edge, where the controls enabled for the workspace are applied. Additional OpenAI fields may serialize for source compatibility but are not server-capability claims. The Go SDK mirrors the Python SDK's transport decisions so the supported wire contract is consistent across both.

Python — osyra-python-sdk

# AFTER — Osyra drop-in (one import + your OSYRA key)
import os
from osyra import OpenAI
 
client = OpenAI(api_key=os.environ["OSYRA_API_KEY"])
 
resp = client.chat.completions.create(
    model=os.environ["OSYRA_MODEL"],
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)

base_url defaults to https://api.osyra.ai/v1 (the wired, OpenAI-compatible edge route). A literal async twin, AsyncOpenAI, shares the same constructor, defaults, auth, and wire shape. Osyra / AsyncOsyra / OsyraOpenAI are native-named import aliases for the same clients.

Go — osyra-go-sdk

import (
	"context"
	"os"
 
	osyra "github.com/osyra-ai/osyra-go"
)
 
client, err := osyra.NewClient(
	osyra.WithAPIKey(os.Getenv("OSYRA_API_KEY")),
)
if err != nil { /* fail-closed: ErrNoAPIKey when no credential is configured */ }
 
resp, err := client.Chat.Completions.Create(context.Background(), osyra.ChatCompletionRequest{
	Model:    os.Getenv("OSYRA_MODEL"),
	Messages: []osyra.Message{{Role: "user", Content: "Hello!"}},
})
if err != nil { /* handle */ }
println(resp.Choices[0].Message.Content)

There is no Async* surface in Go by design — the context.Context-aware blocking API plus goroutines is the Go-idiomatic analog of Python's AsyncOpenAI. The Go SDK has no third-party dependencies (net/http, encoding/json, bufio only).

What both gateway SDKs do

• Chat completions with the Edge-verified request fields: model, non-empty string-role/string-content messages, max_tokens, temperature, top_p, stop, stream, and stream_options.include_usage. Additional OpenAI-shaped fields may serialize for source compatibility; serialization is not a server-capability claim.

• Streaming — SSE parsing into typed chunks, [DONE] termination (sync + async iterators in Python; Recv()/Close() in Go).

• Embeddings via /v1/embeddings.

• Models listing, OpenAI /v1/models-shaped, served off the wired deployment broker catalog. The current response carries ID/ownership metadata; it is not a workspace-policy or operation-capability decision.

• Osyra extras — three governance knobs projected onto X-Osyra-* request headers, never into the OpenAI request body, so the same code still works against a native OpenAI endpoint for A/B testing:

  | knob | wire header | meaning | |---|---|---| | workspace | X-Osyra-Workspace | optional equality assertion against the credential's authoritative workspace; it cannot switch tenants | | cache TTL | X-Osyra-Cache-TTL (+ X-Osyra-Cache) | semantic-cache override; omitted inherits server/workspace behavior, while explicit disable emits X-Osyra-Cache: disabled | | PII mask | X-Osyra-PII-Mask | force PII masking (bool or strategy string) |

• Typed error mapping (401/403/404/400/429/5xx) carrying status, body, and request id. Automatic retry is limited to safe model-list GET requests; inference POSTs are never replayed without an idempotency contract.

Authentication transport

The API-key transport is wired in the SDKs and Edge. In an API-key-enabled deployment, IAM issues osy_(sandbox|test|live)_<43 base64url> keys and the native SDKs send an exact key only as X-Api-Key; OAuth access tokens and token-provider results use only Authorization: Bearer. Both SDKs reject caller attempts to override the credential headers and never emit both.

API-key issuance is separately deployment-gated: IAM requires API-key crypto plus a KMS HMAC key. Without both, management/minting fails closed with 501 OSY-SERVER-9050, while presenting a key to Edge currently returns 503 OSY-SERVER-9002 because its IAM verifier is unavailable. Use OAuth client credentials there.

Upstream OpenAI SDKs cannot select X-Api-Key, so Edge accepts an exact Osyra key in Authorization: Bearer only on the exact /v1 Chat Completions, streaming, Embeddings, and Models method/path tuples.

Native osyra.* surface and pending methods

Both SDKs expose a native namespace (client.osyra.* in Python, client.Osyra.* in Go). models() is wired. estimate_cost / routing_decision / provider_health map to broker RPCs that exist but have no edge REST projection yet — they raise a typed not-implemented error (OsyraNotImplementedError in Python; a *NotImplementedError matchable via errors.Is(err, osyra.ErrNotImplemented) in Go) that names the missing route, rather than fabricating data.

Get started: Gateway SDK getting-started

Family 2 — OME / Verified-Memory SDKs (attested agent memory)

Use these today only for offline verification of OME evidence obtained through an authorized, trusted channel. The Python and TypeScript SDKs are v1.0.0 pre-releases. Their customer network path is not released.

The runnable customer-side capability is local cryptographic verification:

• Verify the exact detached Form-B signing-preimage bytes; do not decode and re-encode them before verification.
• Supply the detached 64-byte Ed25519 signature.
• Supply an independently trusted 32-byte Ed25519 public key. An in-band signer key is attacker-controlled and is not a trust anchor.

Use the committed real vectors under AP00013-osyra-ome-sdk-python/tests/kat/verify-v1/claim-preimage-kat-v1.json and their provenance file when reproducing the verification flow. The TypeScript sibling replays the committed subset from its own tests/kat/verify-v1/ directory. The language-specific guides load those real fixtures; this overview deliberately does not invent claim IDs, workspaces, keys, signatures, or receipts.

The Python and TypeScript implementations also differ in important wire details that currently block a trustworthy live write-to-verify demonstration. Follow the language-specific guide for those limitations. Do not present memory.write* or memory.get* as a production customer flow until the Edge bridge and real acceptance evidence land.

Get started: OME SDK guide — Python · OME SDK guide — TypeScript

Choosing a family

| If you want to… | Use | Languages | |---|---|---| | Call models (chat / embeddings) through OSYRA with one import change | Gateway SDKs | Python, Go | | Verify trusted OME evidence offline from an authorized pre-release checkout | OME / Verified-Memory SDKs | Python, TypeScript | | Write or read OME memory through the supported customer Edge route | Pending — do not target AP00011 directly | Python, TypeScript protocol clients exist |

The two families are independent. A future application can route llm traffic through a gateway SDK and use the OME family for memory, but today the supported combined posture is gateway inference plus offline verification of trusted OME evidence—not live customer memory write/read.

Related

• Gateway SDK getting-started
• OME SDK guide — Python
• OME SDK guide — TypeScript