Live examples for TypeSafeSDK 0.4.1

Every standalone live_*.exs entrypoint uses the real TypeSafeSDK -> generated operation -> Pristine HTTP path. There are no fixtures, recordings, local fake servers, offline success modes, or network-failure fallbacks in these scripts. Synthetic inputs are used to keep the examples safe and reproducible; all advertised live outputs come from the selected API endpoint. Calls may incur charges.

Select the endpoint and model first

The examples are not tied to one vendor hostname. With no endpoint/model override, the SDK defaults remain https://api.typesafe.ai and jev-latest. To use another TypeSafe-compatible deployment, set all credentials and identifiers for that provider deliberately:

export TYPESAFE_API_KEY='credential-issued-for-this-endpoint'
export TYPESAFE_BASE_URL='https://provider.example/deployments/my-typesafe-root'
export TYPESAFE_DEFAULT_MODEL='provider-model-id'

bash examples/run_all.sh

TYPESAFE_BASE_URL is the API root before the generated /v1/models and /v1/systemone operation paths. A path prefix is allowed and is retained, so the example above targets:

https://provider.example/deployments/my-typesafe-root/v1/models
https://provider.example/deployments/my-typesafe-root/v1/systemone

The selected endpoint must implement the TypeSafe operation/request/response contract and bearer authentication expected by this SDK. A generic OpenAI-compatible endpoint is not automatically TypeSafe-compatible. API keys, model IDs, supported operations, and deployment URLs belong to the selected provider; never send a credential issued by one provider to a guessed third-party URL. No provider-specific Cloudflare URL or model is assumed here.

Explicit executable options win over environment/host defaults. The evaluation CLI accepts --base-url and --model; mix typesafe.record accepts the same options. Standalone scripts use TYPESAFE_BASE_URL and TYPESAFE_DEFAULT_MODEL, then fall back to host application config/defaults. Blank or invalid explicit endpoint/model settings fail instead of silently contacting another provider.

For ordinary application code, construct the client explicitly when that makes provider selection clearest:

client =
  TypeSafeSDK.new_client(
    api_key: provider_key,
    base_url: "https://provider.example/deployments/my-typesafe-root",
    model: "provider-model-id"
  )

Or map the same environment names in the host application's config/runtime.exs (a dependency's runtime config does not configure its host):

import Config

config :typesafe_sdk,
  api_key: System.fetch_env!("TYPESAFE_API_KEY"),
  base_url: System.get_env("TYPESAFE_BASE_URL", "https://api.typesafe.ai"),
  default_model: System.get_env("TYPESAFE_DEFAULT_MODEL", "jev-latest")

Runtime modules under lib/** do not read OS environment variables. Executable examples/Mix tasks may do so in order to make live endpoint selection explicit.

Run everything

Run from the repository root after the source-checkout dependency/bootstrap steps in the main README:

read -rsp "TypeSafe API key: " TYPESAFE_API_KEY
echo
export TYPESAFE_API_KEY
# Optional alternate provider settings:
# export TYPESAFE_BASE_URL='https://provider.example/deployment-root'
# export TYPESAFE_DEFAULT_MODEL='provider-model-id'

bash examples/run_all.sh

The runner stops on failure. Retries are disabled by default. Its bounded default path has a 63-request hard upper bound across the standalone scripts plus the 12 development and eight held-out evaluation rows. Conditional recursive and cancellation branches can make fewer requests. Setting TYPESAFE_EXAMPLE_RETRY=1 explicitly enables one bounded retry-configuration operation (max_retries: 1), adding at most two HTTP attempts (65 total attempts for the full runner). Do not blindly rerun an ambiguous failure: remote processing may already have happened.

Runnable catalog

support/live.exs and evaluation/evaluation.exs are supporting modules, not standalone entrypoints. See the evaluation README for the full CLI.

0.2 -> 0.4 feature-to-example matrix

“Live” means a runnable path exercises the real external API. “Deterministic” identifies guarantees that are more honestly asserted in tests/tooling because a successful network response cannot force every error/race/future condition.

Cancellation, failures, and privacy

A real request can complete before cancellation wins. Both completion and typed :cancelled outcomes are legitimate in live_runtime_controls.exs; the example uses no arbitrary delay or fake slow transport. Cancellation stops/cleans local work according to advertised Pristine capabilities but does not prove remote non-execution or rollback.

TypeSafeSDK.OTP.Server creates a private cancellation token for each worker. A caller-provided token remains caller-owned; a watcher only mirrors caller cancellation inward. The live OTP example checks that normal private cleanup does not mutate the caller token. Deterministic shutdown/worker-exit/saturation cases remain in ExUnit rather than manipulating a paid service into failure.

The shared failure path prints only bounded structural Error.metadata. Do not replace synthetic example state with private data unless you intend that data to be sent to the selected provider. API keys are never printed.

Evaluation and live capture entrypoints

The evaluation CLI exposes its endpoint/model workflow directly:

mix run examples/evaluation/run.exs -- --help
mix run examples/evaluation/run.exs -- \
  --base-url "$TYPESAFE_BASE_URL" \
  --model "$TYPESAFE_DEFAULT_MODEL" \
  --split development --sweep --output tmp/examples/development.json

The live capture task follows the same precedence:

mix typesafe.record \
  --base-url "$TYPESAFE_BASE_URL" \
  --model "$TYPESAFE_DEFAULT_MODEL" \
  --output tmp/live --baseline test/fixtures/live

Only use those explicit options when the matching endpoint, credential, and model are actually authorized. The scheduled .github/workflows/live.yml capture also accepts optional repository variables TYPESAFE_BASE_URL and TYPESAFE_DEFAULT_MODEL; the existing TYPESAFE_API_KEY secret must correspond to that selected endpoint. Reports/captures go under ignored tmp/ paths; no example publishes, tags, commits, or updates approved fixtures automatically.