CortexDB SDK Surface

This directory contains Beta HTTP clients for early integrations and package publication dry-runs. They target the stable /v1/* cortex-server surface and intentionally keep runtime dependencies small.

• python/cortexdb_client.py: stdlib Python client with PyPI metadata.
• typescript/cortexdb-client.js: fetch-based JavaScript runtime entrypoint.
• typescript/cortexdb-client.d.ts: TypeScript declarations.
• typescript/cortexdb-client.ts: TypeScript source reference.
• crates/cortex-api-types: shared serde wire types used by server and Rust SDK.
• crates/cortex-sdk: Rust HTTP client published as cortexdb-sdk. It exports the blocking CortexDbClient by default and AsyncCortexDbClient when the async feature is enabled.

The SDK APIs are Beta contracts and may still receive additive changes. Search clients expose a typed response shape with search_mode, ann_report, and ranked results so ANN fallback behavior is visible to callers. ANN evaluation clients expose the /v1/search/ann-evaluate contract as a typed response with exact top-k, ANN top-k, overlap, and fixed-point recall_q16. ann_report also exposes recall_q16, min_recall_q16, hnsw_ef_construction, production_safe, fallback_performed, and slo_violations so clients can enforce ANN/HNSW recall, fallback, graph-shape, and visit-budget guardrails. All clients support additive tenant/realm scoping so package users can target the same per-tenant database layout exposed by cortex-server and /dashboard. All clients also expose AQL builder helpers for RETRIEVE CONTEXT, VERIFY FACT, and REMEMBER so common integrations do not have to assemble query strings by hand. publish/check.sh validates Python bytecode/tests/wheel packaging, Rust tests with all Rust SDK features, cortex-api-types packaging, SDK version consistency, tenant routing, ANN evaluation surface presence, shared API type contracts, and npm package dry-runs when npm is installed. OpenAPI is the source of truth for generated schema-shaped SDK type artifacts: scripts/generate_openapi_sdk_types.py emits typescript/cortexdb-client/generated/openapi-types.ts and python/_cortexdb_client/generated/openapi_types.py from docs/openapi.yaml. The generated types use the OpenApi* prefix so they can coexist with the hand-written ergonomic client models. Rust keeps using the shared cortex-api-types wire structs instead of a second generated Rust type layer; make openapi-contract-check still gates Rust/server/schema drift through live response validation, error taxonomy checks, generated SDK type freshness, and SDK surface drift checks. Publish order matters for Rust: publish cortex-api-types first, then rerun with CORTEX_API_TYPES_PUBLISHED=1 so cortexdb-sdk package verification can resolve the new dependency from crates.io. make sdk-contract-check validates live API compatibility by building the current cortex-server binary and running Python, TypeScript, and Rust SDK smoke tests against real /v1/* responses. The smoke contract covers health, put/get, search, stats, validate, AQL, Context Pack, Verify Fact, Remember, ingest text, and structured error decoding for invalid_aql, not_found, and invalid_tenant. sdk/release-manifest.json records the package names, registries, dry-run commands, deprecation policy, and manual tag-gated publish policy. make sdk-release-contract-check validates that lifecycle contract without building packages. make sdk-release-artifacts-check packages Rust, Python, and TypeScript examples into a checksummed tarball under target/sdk-release-artifacts/ so the release train carries runnable examples alongside package dry-runs.

Use make sdk-check for the local gate. The GitHub SDK Release workflow runs the same preflight on SDK changes and can publish all three packages manually from a version-matching v* tag through the protected sdk-release environment after registry credentials are configured. See docs/archive/SDK_RELEASE.md.