Models

Every response of the SDK is validated with a Zod schema, and its TypeScript type is inferred from that schema, so the two can’t disagree. A model is exported as a schema and a type of the same name, e.g. Guardrail: the schema validates, and the type annotates.

import { Guardrail } from "@smarter.sh/api";

const guardrail: Guardrail = Guardrail.parse(JSON.parse(text));

Every schema keeps fields that it doesn’t declare, so that the SDK keeps working when the platform adds fields to a response. A model’s fields are the API’s own names, exactly as the API returns them, camelCase for the REST resources (hashedId) and snake_case for the chat contract (session_key), so JSON.stringify() of a response is the platform’s JSON. Timestamps are ISO 8601 strings.

SAM types

The SDK has a TypeScript type of every manifest kind, e.g. SAMLLMClient, SAMGuardrail and SAMSecret. SAMKinds maps each kind to its type, and SAM_KINDS lists the kinds.

import { SAM_KINDS } from "@smarter.sh/api";

const llmclient = (await client.llmClients.describe("customer_support")).toSam("LLMClient");
console.log(llmclient.spec.config.prompt.provider, llmclient.spec.config.prompt.defaultModel, llmclient.status?.deployed);
console.log(SAM_KINDS);

The platform’s own manifest models depend on Django, so the SDK can’t import them. Its types are generated from the JSON Schema that the platform publishes for each kind, which is the same schema that client.manifests.jsonSchema(kind) returns, and toSam() validates a manifest against that schema with Ajv. The tests check that every kind’s example manifest validates. The schemas check a manifest’s structure. The platform’s models also apply business rules that a JSON Schema can’t express, so validate a manifest with client.manifests.validate() before you rely on it.

API contracts

The platform publishes the contracts of its APIs as Pydantic models, and the SDK mirrors them as Zod schemas, with the platform’s model names:

SDK schemas	Platform contract
`PromptChatApi...`	The Smarter Chat API contract, version 2: an LLMClient’s configuration (`PromptChatApiConfig`), the prompt API’s request and response, and the prompt’s progress events.
`SAMJournalApi...`, `JournalEntry`, `JournalPage`	The Smarter Journal contract: the envelope of every journaled response, its error body, and a journal entry.
`ViteManifest`, `ReactAppAssets`	The Django-React integration contract: a React app’s Vite manifest, and the assets that a template includes, for tools that build React apps for a Smarter platform.

The SDK’s tests compare the chat and journal mirrors with the platform’s committed JSON Schemas and examples, and fail when the platform adds a field that the SDK doesn’t declare yet.

REST models

The other schemas model the REST API’s resources, e.g. LLMClient, Guardrail and Vectorstore.