semiont 0.6.12__tar.gz

semiont-0.6.12/.gitignore

@@ -0,0 +1,126 @@
+# Dependencies
+node_modules
+.npm-stage
+
+# Local Verdaccio registry (build_and_install_locally.sh)
+.verdaccio/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Environment files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Build outputs
+packages/*/dist/
+dist/
+# transient tsc output: packages/core's build emits it, then rm -rf's it at the end
+dist-types/
+build/
+apps/browser/public
+
+# Testing
+coverage/
+*.lcov
+.nyc_output
+test-results.json
+playwright-report/
+test-results/
+
+# Logs
+logs
+*.log
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.settings/
+*.sublime-project
+*.sublime-workspace
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+*.temp
+
+# Cache directories
+.cache/
+.parcel-cache/
+.eslintcache
+
+# TypeScript
+*.tsbuildinfo
+
+# Generated types and copied specs (NOT the source OpenAPI spec!)
+packages/core/openapi.json
+packages/core/src/types.ts
+packages/core/src/generated/
+packages/core/src/config/config.types.ts
+
+# Python: an environment, and what the interpreter and its tools cache
+.venv/
+__pycache__/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Generated OpenAPI bundle (source is specs/src/)
+specs/openapi.json
+specs/archivist.openapi.json
+
+# Compiled scripts (should use tsx, not tsc)
+packages/*/scripts/*.js
+packages/*/scripts/*.js.map
+packages/*/scripts/*.d.ts
+packages/*/scripts/*.d.ts.map
+# Note: apps/*/scripts/*.js removed - these are actual source JS files, not compiled output
+apps/*/scripts/*.js.map
+apps/*/scripts/*.d.ts
+apps/*/scripts/*.d.ts.map
+
+# Ephemeral Planning Documents
+.plans
+
+# Assembled by scripts/release/notes-context.sh; quotes .plans content verbatim
+.release-notes-context.md
+
+# Compliance audit generated files
+**/scripts/symbols.json
+# Generated compliance reports (all of them — never enumerate outputs by hand)
+.compliance/
+
+# tesseract.js language data — fetched at runtime into the working directory.
+# NOT a source artifact: the images vendor it at build time (OCR is core and
+# must never CDN-fetch in production; SMELTER-MEDIA-TYPES decision 8).
+*.traineddata
+
+# Backups written beside .env.local by tooling
+.env*.backup*
+
+# Cargo's build output, for the whole Rust workspace (Cargo.toml).
+/target

semiont-0.6.12/PKG-INFO

@@ -0,0 +1,533 @@
+Metadata-Version: 2.5
+Name: semiont
+Version: 0.6.12
+Summary: The Python SDK for Semiont, an open platform for building trusted AI knowledge bases
+Project-URL: Homepage, https://the-ai-alliance.github.io/semiont/
+Project-URL: Documentation, https://github.com/The-AI-Alliance/semiont/blob/main/docs/builder/README.md
+Project-URL: Repository, https://github.com/The-AI-Alliance/semiont
+Project-URL: Issues, https://github.com/The-AI-Alliance/semiont/issues
+Project-URL: Changelog, https://github.com/The-AI-Alliance/semiont/releases
+License-Expression: Apache-2.0
+Keywords: agents,annotation,knowledge-base,sdk,semiont
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: opentelemetry-api<2,>=1.30
+Requires-Dist: pydantic<3,>=2.12
+Description-Content-Type: text/markdown
+
+# semiont
+
+The Python SDK for [Semiont][semiont], an open platform for building trusted
+AI knowledge bases: a shared workspace where humans and AI agents annotate,
+connect and govern a corpus of documents.
+
+This package is the client. With it a program reads and writes one knowledge
+base: it adds resources, annotates and links them, searches them, gathers
+context for a model, and hears what the other participants do as they do it.
+A person's application and an AI agent use the same client. The SDK does not
+tell them apart.
+
+It has the same namespaces, methods and live queries as the
+[TypeScript SDK][sdk-typescript] and the [Rust SDK][sdk-rust], and is held to
+the same [conformance suite][conformance]. New to Semiont? The
+[Introduction][introduction] explains the domain and the ideas the API falls
+out of. Its code is TypeScript, and the ideas are this package's too.
+
+## Install
+
+```bash
+pip install semiont
+```
+
+It requires Python 3.12 or later, and runs on asyncio. It is checked by
+`mypy --strict` and by `pyright` in strict mode, and ships its types
+(`py.typed`): a wrong id, a wrong payload for a channel and an unhandled code
+or state are errors a type checker reports.
+
+One package holds all of it: the client, the transport that carries it over
+HTTP to a knowledge base's gateway, signing in, and the doubles a test is
+built on. Its dependencies are `httpx`, `pydantic` and `opentelemetry-api`.
+
+A client speaks to a running knowledge base. The [Quick Start][quick-start]
+sets one up on your own machine.
+
+## The client
+
+A client is the eleven namespaces over one transport: `frame`, `browse`,
+`mark`, `bind`, `gather`, `match`, `yield_` and `beckon`, one per
+[flow of the protocol][protocol], and `job`, `auth` and `system` beside them.
+`yield` is Python's own word, so its namespace is `yield_`. Each method is a
+row of [`specs/src/client/surface.json`][surface], the table every Semiont SDK
+is held to. `HttpTransport` is the transport this package ships: it reaches a
+knowledge base's gateway, and sends the token it is given.
+
+```python
+from semiont.client import SemiontClient
+from semiont.http import HttpTransport
+from semiont.identifiers import AnnotationId, ResourceId
+from semiont.namespaces.follow import JobAttemptFailed, JobCompleted, JobProgressed
+from semiont.namespaces.mark import MarkAssistOptions
+from semiont.transport import Transport
+from semiont.watched import Variable
+
+
+async def annotate(client: SemiontClient[Transport], resource: ResourceId, annotation: AnnotationId) -> None:
+    described = await client.browse.resource(resource).fresh()  # a query, read once
+    text = await client.browse.resource_content(resource)  # asked once, answered once
+    print(described.name, len(text))
+
+    async for event in client.mark.assist(resource, "highlighting", MarkAssistOptions()):  # a job, followed
+        match event:
+            case JobProgressed(data=progress):
+                print(progress.percentage)
+            case JobAttemptFailed(data=setback):
+                print("trying again after:", setback.error)
+            case JobCompleted(data=done):
+                print(done.result)
+
+    reached = await client.beckon.attention(resource, annotation)  # a drive: how many the gateway reached
+    client.browse.click(annotation)  # a signal: this viewer's own, never sent
+    print(reached)
+
+
+async def over_http(origin: str, token: str, resource: ResourceId, annotation: AnnotationId) -> None:
+    async with (
+        HttpTransport(origin, token=Variable[str | None](token)) as transport,
+        SemiontClient(transport, transport.content, transport) as client,
+    ):
+        await annotate(client, resource, annotation)
+```
+
+Every method returns one of seven shapes, and the table says which:
+
+| Shape | In Python | |
+|---|---|---|
+| asked once, answered once | `async def` | a failure is raised |
+| a long-running operation | `Running[T]` | awaited for its final value, or read with `async for` for every report and then the final value; one or the other, once |
+| an upload | `Upload` | awaited for the resource it created, read for its progress |
+| a query | `Cached[T]` | building it sends nothing; `await query.fresh()` reads it once, and held with `async with` it is watched |
+| a signal | `def`, returning nothing | published on the client's own bus, or sent and not awaited |
+| a drive | `async def` giving `int \| None` | how many participants the gateway reached, or nothing when it kept no count |
+| a channel's events | `Typed[P]` | `async for`, each event's payload decoded |
+
+- **A followed job** (`mark.assist`, `yield_.from_context`) reports its
+  progress and ends with its completion. A job that says nothing is asked for
+  its status, so a completion the stream did not carry is still heard. It ends
+  as a `JobError` when the job failed for good, was cancelled, or (a
+  generation) said nothing for longer than its length allows.
+- **`client.bus`** is the client's own bus: every frame its transport
+  delivered, and every signal its own parts gave each other.
+  **`client.wire`** is the bus over the transport, typed by channel.
+- **A client is held with `async with`**: inside, it listens for what keeps
+  its queries true, and it ends what it started on the way out. It does not
+  close its transport: whoever opened that closes it, after the client. A
+  session (`session_from_kept`) holds one as `session.client`.
+- **A client is generic in its transport.** Code that takes a
+  `SemiontClient[Transport]` runs over HTTP and over a test's doubles alike.
+- **What it sends unasked is the table's**: a list's first hundred, a
+  search's ten candidates, a context's two thousand characters. An option
+  given as `None` is an option not given, and is not sent.
+
+Why the shapes are these seven, in every SDK, is
+[the reactive model][reactive-model].
+
+## Signing in
+
+A transport sends the token it is given. Where the token comes from is one of
+three things, and each keeps it renewed: half its lifetime before it expires,
+at most five minutes before, and at once when the gateway refuses it.
+
+**An agent** is a service account's token exchanged at the gateway for the
+token of the agent `(provider, model)`. It is what a service holds: a
+transport, its agent's token, and the channels it awaits replies on.
+
+```python
+from semiont.bus import reply_channels_for
+from semiont.http import AgentToken, Credential, HttpTransport, ServiceToken
+from semiont.operations import JOB_CLAIM
+from semiont.watched import reached
+
+
+async def work(gateway: str, issuer: str, secret: str) -> None:
+    service = ServiceToken(Credential(issuer=issuer, client_id="semiont-smelter", client_secret=secret))
+    async with (
+        AgentToken(gateway, provider="ollama", model="gemma2:27b", service=service) as agent,
+        HttpTransport(gateway, token=agent.token, refresher=agent.refresh, channels=reply_channels_for(JOB_CLAIM)) as transport,
+    ):
+        print(await reached(transport.state, lambda state: state == "open"))  # its stream is open, as the agent
+```
+
+**A person** is signed in at the issuer the knowledge base trusts, and the
+sign-in is kept. [`semiont login`][launcher] keeps one for each stack, and a
+session here is built over it; a script on a machine with no launcher makes
+its own by the device grant, which shows a code to approve in any browser. No
+password passes through this process.
+
+```python
+from pathlib import Path
+
+from semiont.http import DeviceCode, session_from_kept, sign_in_device
+from semiont.sign_in_store import FILE_NAME, SignInStore, state_dir, this_system
+
+
+def show(code: DeviceCode) -> None:
+    print(f"Open {code.verification_uri} and enter {code.user_code}")
+
+
+async def as_me(gateway: str, home: str) -> None:
+    directory = state_dir(this_system(), home=home, xdg_state_home=None, local_app_data=None)
+    if directory is None:
+        return
+    kept = SignInStore(Path(directory) / FILE_NAME).entry("local")
+    if await kept.held() is None:
+        await sign_in_device(gateway, kept, show)
+    async with session_from_kept(gateway, kb_id="local", kept=kept) as session:
+        print(session.user.value, (await session.client.system.status()).version)
+```
+
+- **An agent whose renewal fails keeps the token it has** and tries again: a
+  process holding a token that still works does not stop over one bad round
+  trip. Signing in is the one step that raises.
+- **A person's session ends once, and says why.** A token the issuer will not
+  renew ends it as `expired`, and a token the issuer has just issued and the
+  gateway refuses ends it as `refused` (`on_auth_failed`). The sign-in is
+  then forgotten, so a dead credential is never sent again. What a session
+  does at its start and when it is refused is
+  [`specs/src/session/cases.json`][session-cases], row for row.
+- **A renewal spends its refresh token once.** Renewals asked for together are
+  one request of the issuer, a renewal the issuer did not refuse is tried
+  again inside a bounded budget, and one under way runs to its end whoever
+  stops waiting for it.
+- **The store is the launcher's** ([`specs/src/sign-in-store`][sign-in-store]):
+  the same file and the same lock, on macOS, Linux and Windows. A sign-in made
+  here serves the launcher's verbs, and one it renewed serves this session.
+  `MemorySignIn` keeps one for the life of the process instead, and
+  `sign_out` revokes one at its issuer and forgets it.
+- **Nothing here reads the environment.** An application reads its own
+  (`HOME`, a secret, an address) and says what it found.
+
+## Live queries
+
+A query is one of ten reads
+([`specs/src/client/refresh.json`][refresh] names them) that answer from the
+client's cache. Read once, it asks the knowledge base now. Held with
+`async with`, it is watched: its state now, and each state after it, until
+the client closes.
+
+```python
+from typing import assert_never
+
+from semiont.cache import Failed, Pending, Ready
+from semiont.client import SemiontClient
+from semiont.identifiers import ResourceId
+from semiont.transport import Transport
+
+
+async def watch(client: SemiontClient[Transport], resource: ResourceId) -> None:
+    async with client.browse.annotations(resource) as live:  # holds the resource's scope
+        async for state in live:
+            match state:
+                case Pending():
+                    print("asking")
+                case Ready(value=annotations):
+                    print(len(annotations), "annotations")
+                case Failed(error=error):  # a state, not a raise: the query lives on
+                    print("failed:", error.code)
+                case _:
+                    assert_never(state)
+```
+
+- **A state is one of three**, and a `match` that leaves one out does not
+  type-check. `Failed` is the state of a query with no value whose request
+  failed and failed again. It is not the end: the next watcher, an event or
+  `query.invalidate()` asks again, and every watcher is shown what comes.
+- **Watching is what asks.** The first watcher of a query starts its request,
+  and watchers that arrive together share it. A later one is given what is
+  held. A request that fails is made once more; a query that has a value
+  keeps showing it whatever its refetches do.
+- **A watched query stays true.** While a query of one resource is held, the
+  client holds that resource's scope, so its events reach the client; and each
+  event asks again for exactly the queries the refresh table gives it, writes
+  the value an event carries, or ends an annotation that is gone. What events
+  ask of one query inside a second is one request. A stream that dropped and
+  returned asks again for what its events could not replay.
+- **A read** (`await query.fresh()`) asks now, raises the failure it meets,
+  and gives every watcher of the query its answer.
+- **A watcher that falls behind** is given the latest state, not each one it
+  missed: a state is what is true now.
+- **A query is watched inside its client's `async with`**, which is what
+  listens for the events. After the client closes, a watcher is given
+  nothing and a read is refused as `bus.closed`.
+- **A client can keep what its small queries hold**
+  (`SemiontClient(..., persistence=CachePersistence(storage=..., key_prefix=...))`),
+  in a `semiont.storage.SessionStorage` the application supplies: a
+  resource's description, its annotations, one annotation, the entity types,
+  the tag schemas. The next client over the same storage shows them at once
+  and asks for each anew the first time it is watched.
+  `session_from_kept(..., storage=...)` does this for a session, and keeps the
+  stream's place in each resource's scope with it (`semiont.resume`), so the
+  next session is sent what was recorded since.
+
+The behaviours every SDK's live queries are held to are numbered in
+[the cache's semantics][cache-semantics].
+
+## Testing what is built on it
+
+`semiont.testing` gives a real client over doubles. Its namespaces, its cache
+and its deadlines are the client's own; only what it speaks through is
+scripted. A test says what the knowledge base answers, runs the code under
+test, and reads what that code asked.
+
+```python
+from semiont.client import SemiontClient
+from semiont.identifiers import ResourceId
+from semiont.testing import create_test_client
+from semiont.transport import Transport
+
+
+async def title_of(client: SemiontClient[Transport], resource: ResourceId) -> str:
+    return (await client.browse.resource(resource).fresh()).name.title()
+
+
+async def a_title_is_its_resources_name_in_title_case() -> None:
+    made = create_test_client()
+    made.transport.queue_reply(
+        "browse:resource-requested",
+        [
+            {
+                "resource": {"@context": "https://schema.org", "@id": "res-1", "name": "a page of notes", "representations": []},
+                "annotations": [],
+                "entityReferences": [],
+            }
+        ],
+    )
+
+    async with made.client as client:
+        assert await title_of(client, ResourceId("res-1")) == "A Page Of Notes"
+
+    # What the code under test asked of the knowledge base, as it was sent.
+    assert [(asked.channel, asked.payload) for asked in made.transport.request_log] == [
+        ("browse:resource-requested", {"resourceId": "res-1"})
+    ]
+    await made.transport.close()
+```
+
+- **`FaultyTransport`** is a transport with no wire. `queue_reply` says what
+  the gateway answers the next requests of an operation with, and
+  `refuse_when` has it answer with a failure. A schedule of `Deliver`,
+  `DropReply`, `Delay`, `DuplicateReply` and `RejectEmit` says what the wire
+  does to each request in turn, so a lost reply and the retry after it can be
+  scripted. `request_log` and `emitted` are what was sent; `deliver` carries a
+  frame in as the bus would; `set_state` drops the stream and brings it back.
+- **`InMemoryContent`** keeps what is uploaded and what a test seeds, and
+  **`StubGateway`** answers the gateway's own operations as a test scripted
+  them. Each records the calls made of it.
+- **A double refuses what nobody scripted, by name.** A request with no
+  answer scripted fails naming its operation, and a read of content nobody
+  stored fails naming the resource. None answers with a value of its own
+  making, so a test that forgot to say something fails where it forgot.
+- **`create_test_client`** takes the doubles a test built, or makes ones
+  nothing is scripted on, and the client's own timing and persistence.
+
+## The bus
+
+Under the namespaces is the bus, and a program can speak on it directly. A
+transport is held with `async with`. Its stream opens inside, once there is
+a token, and everything it started has ended on the way out.
+
+```python
+from semiont.bus import Bus
+from semiont.channels import MARK_ADDED
+from semiont.errors import BusRequestError
+from semiont.http import HttpTransport
+from semiont.identifiers import ResourceId
+from semiont.operations import BROWSE_RESOURCE_REQUESTED
+from semiont.types import BrowseResourceRequest
+from semiont.watched import Variable
+
+
+async def read(origin: str, token: str, resource: ResourceId) -> None:
+    async with HttpTransport(origin, token=Variable[str | None](token)) as transport:
+        bus = Bus(transport)
+        try:
+            reply = await bus.request(BROWSE_RESOURCE_REQUESTED, BrowseResourceRequest(resource_id=resource))
+        except BusRequestError as error:
+            print(error.code)  # "bus.not-found", "bus.timeout", …: a closed vocabulary
+            return
+        print(reply.response.resource.name)
+
+        # Frames arrive on a resource's channels while its scope is held.
+        with transport.subscribe_to_resource(resource):
+            async with bus.frames(MARK_ADDED) as added:
+                async for frame in added:
+                    print(frame.scope, frame.payload.type)
+```
+
+- **The bus is typed by channel.** A channel is a constant that carries its
+  payload's type: a request is refused another operation's payload, its reply
+  is that operation's result, and a frame's payload is its channel's. By
+  name, with JSON objects, it is `semiont.bus.request` and the transport's
+  own `emit` and `frames`.
+- **A request** waits for the stream to be open before it is sent, is answered
+  once, and is abandoned by cancelling the task that awaits it.
+- **Frames** are a sequence: each reader is given every one, in order, however
+  far behind it falls.
+- **The connection's state** (`transport.state`) is a value: what it is now,
+  and each thing it becomes. A dropped stream is a state, never an error, and
+  opens again by itself.
+- **Failures** are `SemiontError`s under the codes of
+  [`specs/src/errors/codes.json`][codes]. What a server refused is also on
+  `transport.failures()`.
+- **The token** is a value the transport watches: when it changes, the next
+  request carries the new one. A stream the gateway refused as unauthorized
+  asks its `refresher` for another token, once per outage, and with none
+  waits, with no request, for a different one.
+
+The protocol it keeps to is [the transport contract][transport-contract] and
+[the HTTP transport][transport-http], and the [conformance suite][conformance]
+holds it there, case by case, beside the TypeScript and Rust SDKs.
+
+## Content, and the gateway's own operations
+
+Bytes never ride the bus. A transport's `content` uploads them and reads them
+back, and the transport itself asks the gateway what a gateway answers for
+itself.
+
+```python
+from semiont.http import HttpTransport
+from semiont.identifiers import ResourceId
+from semiont.transport import PutBinaryRequest
+
+
+async def store(transport: HttpTransport, page: bytes) -> ResourceId:
+    upload = transport.content.put_binary(
+        PutBinaryRequest(name="A page", file=page, format="text/markdown", storage_uri="file://pages/a.md", entity_types=["Note"])
+    )
+    async for progress in upload:
+        print(progress.bytes_uploaded, "of", progress.total_bytes)
+    created = await upload
+
+    stored = await transport.content.get_binary(created.resource_id)
+    assert (stored.data, stored.content_type) == (page, "text/markdown")
+    async with await transport.content.get_binary_stream(created.resource_id) as arriving:
+        async for piece in arriving:
+            print(len(piece))
+
+    me = await transport.get_current_user()
+    print(me.did, (await transport.health_check()).status)
+    return created.resource_id
+```
+
+- **An upload** is awaited for the resource it created and iterated for its
+  progress, each once. Its caller abandons it by cancelling the task that does
+  either: its connection closes, and nothing is reported.
+- **What is read is what was stored**, byte for byte, with its media type. A
+  time or a URI in an answer is the text the gateway sent, and a field it sent
+  as null is `None`.
+- **A read is asked a second time** when the gateway says it will recover, or
+  says nothing. A request that may already have had its effect is not.
+
+## Ids, and the protocol's shapes
+
+The package holds what the protocol states, as Python types: the kinds of id,
+the shapes the protocol sends and answers with, the channels of its bus and
+the requests made over them. Each kind of id is a type of its own, made only
+from text that is one, and a type checker refuses one kind where a shape
+names another.
+
+```python
+from semiont.identifiers import AnnotationId, InvalidIdentifier, ResourceId
+from semiont.types import MarkDeleteCommand
+
+resource = ResourceId("5bcd259ab1464cf68a556bbad21f513f")
+assert ResourceId.parse("not an id") is None  # where text that is not an id is an ordinary answer
+try:
+    ResourceId("https://kb.example/resources/x")
+except InvalidIdentifier as refused:
+    print(refused)  # 'https://kb.example/resources/x' is not a ResourceId: it does not match ^[A-Za-z0-9_-]{1,128}$
+
+command = MarkDeleteCommand(annotation_id=AnnotationId("a-1"), resource_id=resource)
+print(command.model_dump(mode="json", exclude_unset=True))
+# {'annotationId': 'a-1', 'resourceId': '5bcd259ab1464cf68a556bbad21f513f'}
+
+# MarkDeleteCommand(annotation_id=resource) is refused by a type checker: a ResourceId is not an AnnotationId.
+```
+
+## Telemetry
+
+The SDK takes OpenTelemetry's API and installs nothing: it does nothing until
+the application it runs in installs a provider. With one, it exports what
+[`specs/src/sdk-telemetry/telemetry.json`][telemetry] lists, as every Semiont
+SDK does: a span for each frame sent and each received, a span for each upload
+and each read, and a count of the emits sent. A request carries the trace it
+is made in, and a frame continues the trace it was sent under (`frame.trace`).
+
+## What is in the package
+
+| Module | What it holds |
+|---|---|
+| `semiont.client` | `SemiontClient`, and the timing it keeps to |
+| `semiont.namespaces` | The methods of each namespace, and the options they take |
+| `semiont.running`, `semiont.cached` | `Running[T]` and `Cached[T]`: what long-running operations and queries return |
+| `semiont.cache`, `semiont.refresh`, `semiont.resume` | The cache queries answer from and its three states, which queries each event asks again, and where a stream resumes after a restart |
+| `semiont.storage` | Where a client keeps what must outlive it: `SessionStorage`, and `MemoryStorage` |
+| `semiont.session` | `SemiontSession`, and `MemorySignIn` |
+| `semiont.http` | `HttpTransport`, and signing in: `ServiceToken`, `AgentToken`, `sign_in_device`, `session_from_kept`, `sign_out` |
+| `semiont.sign_in_store` | The sign-ins `semiont login` keeps, and where each system keeps them |
+| `semiont.identifiers`, `semiont.types` | The kinds of id, and every request, response and event |
+| `semiont.channels`, `semiont.operations` | The bus's channels and its operations, each a constant that carries its payload's type |
+| `semiont.bus`, `semiont.event_bus` | The typed client of the bus over a transport, and a client's own in-process bus |
+| `semiont.transport` | The contract a transport implements: `Transport`, `ContentTransport`, `GatewayOperations` |
+| `semiont.errors`, `semiont.timing`, `semiont.retry` | The failure codes, the deadlines and the retry rules every Semiont SDK shares |
+| `semiont.watched`, `semiont.events` | A value that changes and a sequence of events: what a state and a channel's frames are read as |
+| `semiont.media_types` | The media types a knowledge base admits, and the rules read from them |
+| `semiont.identity` | How a knowledge base is named, and the principals who act in it |
+| `semiont.telemetry` | What the transports tell OpenTelemetry |
+| `semiont.testing` | The doubles: `FaultyTransport`, `InMemoryContent`, `StubGateway`, `create_test_client` |
+
+Nothing here restates the protocol by hand. `identifiers`, `types`,
+`channels`, `operations`, `error_codes`, `timing`, `refresh`,
+`telemetry_table`, `oauth_clients`, `sign_in` and `media_types_table` are
+generated from the [specification][specs], and a gate in CI fails when one of
+them differs from what the specification generates.
+
+## Working on it
+
+The package is [`packages/sdk-python`][package] of the
+[Semiont repository][semiont], and [Testing][testing] says how its checks and
+its tests are run. The programs this page shows are files of its tests, word
+for word: both type checkers check them, and each one is run.
+
+## License
+
+Apache-2.0. See [LICENSE][license].
+
+[semiont]: https://github.com/The-AI-Alliance/semiont
+[introduction]: https://github.com/The-AI-Alliance/semiont/blob/main/docs/builder/INTRODUCTION.md
+[quick-start]: https://github.com/The-AI-Alliance/semiont/blob/main/docs/builder/QUICK-START.md
+[reactive-model]: https://github.com/The-AI-Alliance/semiont/blob/main/docs/builder/REACTIVE-MODEL.md
+[protocol]: https://github.com/The-AI-Alliance/semiont/blob/main/docs/protocol/README.md
+[transport-contract]: https://github.com/The-AI-Alliance/semiont/blob/main/docs/protocol/TRANSPORT-CONTRACT.md
+[transport-http]: https://github.com/The-AI-Alliance/semiont/blob/main/docs/protocol/TRANSPORT-HTTP.md
+[cache-semantics]: https://github.com/The-AI-Alliance/semiont/blob/main/docs/protocol/CACHE-SEMANTICS.md
+[conformance]: https://github.com/The-AI-Alliance/semiont/blob/main/tests/conformance/sdk/README.md
+[sdk-typescript]: https://github.com/The-AI-Alliance/semiont/blob/main/packages/sdk/README.md
+[sdk-rust]: https://github.com/The-AI-Alliance/semiont/blob/main/packages/sdk-rust/README.md
+[launcher]: https://github.com/The-AI-Alliance/semiont/blob/main/apps/launcher/README.md
+[specs]: https://github.com/The-AI-Alliance/semiont/blob/main/specs/README.md
+[surface]: https://github.com/The-AI-Alliance/semiont/blob/main/specs/src/client/surface.json
+[refresh]: https://github.com/The-AI-Alliance/semiont/blob/main/specs/src/client/refresh.json
+[codes]: https://github.com/The-AI-Alliance/semiont/blob/main/specs/src/errors/codes.json
+[session-cases]: https://github.com/The-AI-Alliance/semiont/blob/main/specs/src/session/cases.json
+[sign-in-store]: https://github.com/The-AI-Alliance/semiont/blob/main/specs/src/sign-in-store/README.md
+[telemetry]: https://github.com/The-AI-Alliance/semiont/blob/main/specs/src/sdk-telemetry/telemetry.json
+[package]: https://github.com/The-AI-Alliance/semiont/tree/main/packages/sdk-python
+[testing]: https://github.com/The-AI-Alliance/semiont/blob/main/docs/contributor/TESTING.md
+[license]: https://github.com/The-AI-Alliance/semiont/blob/main/LICENSE