SDKs

What they areCopy Anchor Link

Loams has one application API: Connect and gRPC services in loams.<service>.v1 packages, served by the loams binary on its main port. The SDKs are thin clients for it in seven languages: TypeScript, Python, Rust, C#, Go, Swift and C++. Each gives you one Loams client object with namespaced modules (loams.instance, loams.live, loams.tables, and so on), typed errors with stable reasons, safe retries with idempotency keys, and streams as the language's own async iteration.

Use an SDK when you call Loams' own API: Loams Live, the instance and admin services, and the generated types for the rest. You do not need one for the compatibility surfaces. Those exist so that unmodified third-party clients work: use qdrant-client, elasticsearch-py, a Postgres or MySQL driver, an ADBC or Flight SQL driver, or a ClickHouse HTTP client against the matching endpoint. And if your language is not in the seven, the API is plain Connect: a unary call is an HTTP POST with a JSON body, so curl or any HTTP client works.

StatusCopy Anchor Link

The seven SDKs are available in Loams 0.1.0 (released 2026-10-18), published from the release tag at version 0.1.0. As with all of 0.x, an API may change between minor versions.

Java, Kotlin, Ruby, PHP, Dart and Objective-C are in the repository and pass the required fixtures there, but are not published; the feature table lists them as in progress.

ArchitectureCopy Anchor Link

How it worksCopy Anchor Link

One API, one portCopy Anchor Link

Every application call is an RPC (D600). The loams main port serves the Connect protocol, gRPC and gRPC-Web at once, plus gRPC health and reflection, so a browser, a server and grpcurl all reach the same handlers. The bespoke REST APIs were removed rather than kept beside it (D602), and the compatibility surfaces (Qdrant, Elasticsearch, Postgres and MySQL wire, Flight SQL and others) stay exactly as they are, because their whole point is that existing clients work unchanged (D603). A service that a build does not carry answers UNIMPLEMENTED with the reason feature_not_in_variant, and GetInstance lists the services a server offers, so an SDK can feature-detect before it calls.

Generated where possibleCopy Anchor Link

The SDKs follow one rule: generate everything that can be generated, and hand-write only the runtime (D606).

• Messages and stubs come from buf generate, never hand-edited.
• The facade, the loams.<module>.<call> surface, is generated from the loams.options.v1 annotations by protoc-gen-loams-facade for TypeScript, Python, Rust and Go. Go generates gen/facade and hand-writes its module file.
• C#, Swift and C++ facades are hand-written today, and each is checked against facade-index.json by a test, so a module or call added to the protos and missing from the SDK fails CI. The API2 plan's owner ruling (Q604) moves Swift and C# to generated facades once their renderers exist.
• The runtime (transport, auth, retry, errors, pagination, the version check) is written once per language.

Names follow each language's case: loams.instance.getInstance in TypeScript, loams.instance with snake_case methods in Python, client.Instance().GetInstance(ctx, ...) in Go.

The runtime contractCopy Anchor Link

What every SDK must do is written down as ten clauses in docs/sdk/runtime-contract.md and decided in D608 to D611:

There is no client or bidirectional streaming in the API: browsers cannot do it, and half-duplex works through every proxy.

The conformance corpusCopy Anchor Link

The fixtures are recorded, not written (D617). sdks/conformance/record-fixtures.mjs captures real answers from loams dev, and from loams-apps-mock for the app packages and for faults a real server cannot produce on demand. sdks/conformance/fixture-server.mjs replays them byte for byte. A hand-written expectation would only prove that an SDK agrees with whoever wrote it; a recording proves it agrees with the server.

Each unary case is recorded in four encodings (application/json, application/proto, application/grpc-web+proto and application/grpc-web+json), because the bodies are not interchangeable and an SDK's transport picks one. The corpus also keeps two traps apart: Connect reports an error as an HTTP status with a JSON body, while gRPC-Web answers 200 and puts the code in the trailers; and a refusal on a stream arrives inside the streaming envelope, not as a status.

sdks/fixtures/manifest.json is the single definition of "passes": a language passes when it has run every fixture marked required. Today that is 28 of 33 fixtures. The suite runs through each SDK's public facade, not its generated stubs.

The corpus is honest about its gaps. Clauses R2 (retries), R4 (consistency tokens) and R6 (pagination) have no recorded fixture yet, so each language pins them against a stub instead. A retryable unavailable needs a dependency to be down, which neither recording server can produce on demand, and recording consistency tokens and paging end to end is part of API2's corpus work.

VersioningCopy Anchor Link

buf breaking runs on every pull request against the last release tag for every package not marked unstable (D616), and SDKs and protos are additive-only within a major version (D939): an SDK minor never removes or renames a public symbol, and the fixtures check it. A reason is never renamed or removed within a major version. Packages marked unstable (Loams Live's loams.live.v1 is one) are excluded from the breaking check, which is why the SDKs label their Live modules as unstable.

Key decisions and whyCopy Anchor Link

From the decision log and the design, §44 The Unified Connect API and the Multi-Language SDKs. The D600 to D619 rows are recorded as proposed with the owner's "do suggested for all" defaults; the API2 plan's owner rulings of 2026-10-10 are binding for execution.

loams.agentd.v1, Loams Studio's daemon API, is deliberately outside the SDK catalogue (Q816): the facade generator's NOT_SDK_PACKAGES keeps it out.

What is compatibleCopy Anchor Link

Install commands and versions from the 0.1.0 release guide; toolchain and library versions from each SDK's own manifest.

What the facades cover today: the TypeScript SDK's modules are instance, auth, admin.org, admin.projects, admin.agents, admin.keys, admin.audit, live, live.admin and tables; the Python SDK has instance, live, tables and system. The generated message types and stubs cover every SDK package, including loams.collection.v1, graph.v1, house.v1, postgres.v1 and repos.v1; facade modules for those come with API2.

How it comparesCopy Anchor Link

There are two common ways to ship database client libraries. Many projects hand-write a client per language and keep them in line with a shared specification and test suite; MongoDB's drivers are the best-known example. Others generate clients from a machine-readable API definition: Google Cloud's client libraries are generated from protobuf service definitions, and Stripe's from its OpenAPI specification.

Where the others are better today: mature hand-written drivers cover every feature of their database in idiomatic depth, and large generated SDKs cover their whole API. The Loams facades cover a few modules so far, and three of the clauses in the runtime contract are pinned against stubs rather than recorded fixtures. Where Loams' approach helps: a new RPC reaches seven languages from one proto change, and every SDK is tested against the same recorded bytes.

What is missing and what is plannedCopy Anchor Link

The API2 plan finishes and supersedes API1, SDK1 and SDK2.

• Six more languages. Java, Kotlin, Ruby, PHP, Dart and Objective-C build and pass the required fixtures in the repository but are not published. The owner's ruling keeps all thirteen; Objective-C is the first to drop if upkeep gets too heavy, and it would ship as generated sources and a SwiftPM target, not CocoaPods (D614).
• The whole API in every facade. Facade modules for collections, graph, House, Postgres and repositories, and a corpus that covers every stable package and every runtime clause (API2 Tasks 13 to 23).
• Generated facades for Swift and C# (Q604; each needs a renderer).
• Recorded fixtures for retries, consistency tokens and pagination (R2, R4, R6), with a fault server that can inject retryable errors.
• Reference docs generated from the proto comments, with snippets taken from the tested fixtures (D618).
• C++ packaging. The C++ stubs build against protobuf 36.1 exactly, so there are no vcpkg or Conan ports yet. Building loams-proto from crates.io needs protoc installed.
• Bulk data. Large results and bulk ingest go through Arrow Flight SQL with an ADBC or Flight driver, not through the SDKs yet; the design's loams.bulk module is planned.

How to try itCopy Anchor Link

Run an engine (see Loams Desktop and the loams CLI) and create an API key with loams auth new-key, with LOAMS_AUTH_MODE=apikey on the stack. Then, in TypeScript:

npm i @loams/client

import { Loams, apiKey, FeatureNotInVariantError } from '@loams/client';

const loams = new Loams({
  endpoint: 'https://acme.loams.dev',
  auth: apiKey(process.env.LOAMS_API_KEY!),
});

const info = await loams.instance.getInstance({});
await loams.system.guard('live');

try {
  await loams.tables.mutate(request);
} catch (error) {
  if (error instanceof FeatureNotInVariantError) {
    console.warn(error.variant);
  }
}

In Python:

pip install loams

from loams import Loams

loams = Loams("https://acme.loams.dev", api_key="...")
print(loams.instance.version())

In Go:

go get loams.dev/go@v0.1.0

client := loams.New(loams.Options{
    Endpoint: os.Getenv("LOAMS_ENDPOINT"),
    Auth:     loams.APIKey(os.Getenv("LOAMS_API_KEY")),
})
info, err := client.Instance().GetInstance(ctx, &loams.GetInstanceRequest{})

Use your own engine's URL as the endpoint, such as https://loams.<tailnet>.ts.net for a compose stack on your tailnet. If a registry does not serve a package yet, use the SDK from the repository at the release tag (sdks/<language>).

SourceCopy Anchor Link

• Design: §44 The Unified Connect API and the Multi-Language SDKs
• Plans: API2, API1, SDK1, SDK2
• Contracts: docs/sdk/runtime-contract.md, docs/api/reasons.md
• Code: sdks/, proto/, crates/loams-facade-gen, sdks/fixtures, sdks/conformance