Metadata-Version: 2.5
Name: albok-client
Version: 0.1.1
Summary: Albok — the clients: the `albok` CLI and the `albok-mcp` stdio server, stdlib-only HTTP clients over the albok-service read API (unit 3; docs/contracts/unit3_clients.contract.md).
Author: Vuong Hoang
License: Proprietary
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# albok-client

The `albok` CLI and the `albok-mcp` stdio server: stdlib-only HTTP clients over
albok-service's read API (unit 3; contract at `docs/contracts/unit3_clients.contract.md`).
The postbox / althing-mcp shape: nothing guessed, an unreachable service is never an empty
result, and the two surfaces expose the same verbs.

## Install

```bash
uv tool install albok-client --index https://gitea.phasefinal.com/api/packages/vh/pypi/simple
```

Both commands read two environment variables and nothing else:

```bash
export ALBOK_SERVICE=http://albok.nh3.internal:8392   # no default: a guessed address reads the wrong store
export ALBOK_TOKEN=<your per-handle token>             # or --token-file PATH; infra-ops mints tokens
```

## `albok`

```
albok search QUERY [--wing B/W]... [--top-k N] [--facet KEY=VALUE]... [--include-tombstoned] [--include CLASS]... [--json]
albok read OBJECT_ID [--extracted] [--include CLASS]...   the pristine bytes, to stdout
albok sidecar OBJECT_ID [--include CLASS]...
albok buildings | albok wings BUILDING
albok facets B/W [KEY] [--include CLASS]...  facet keys, or one key's values with counts
albok objects B/W [--facet KEY=VALUE]... [--include CLASS]...
albok health | albok status                aggregate health | the wings this token can read
albok ingest [nemi args]                   execs `nemi run …` (Nemi owns ingestion)
```

Exit codes: 0 ok · 1 the service refused (the error on stderr) · 2 unreachable · 3 no token ·
4 no address · 5 something answered that is not albok-service (no `X-Albok-Service` header, or a
shape this client cannot render; try `--json`) · 64 usage.

Every sidecar key is a facet: `--facet structure.repo=albok`, `--facet derived.entities=worldtree`,
`--facet structure.entry_date=2026-10-02`, `--facet kind=section`.

Objects in a sensitivity class (`adult`, `personal`, `secret`) are hidden by default; `--include CLASS`
asks for one back, and the service honours it only where your token holds that class. When your token
holds a class on a searched wing, the search prints `hidden: secret 2, … — including a class may change
the answer` under the results (service 0.1.13 and later). The MCP tools take the same `include` array.

## `albok-mcp`

A stdio JSON-RPC 2.0 server (protocol `2025-11-25`) with nine read-only tools: `albok_search`,
`albok_read`, `albok_sidecar`, `albok_buildings`, `albok_wings`, `albok_facets`, `albok_objects`,
`albok_health`, `albok_status`. Claude Code registration:

```bash
claude mcp add albok -e ALBOK_SERVICE=http://albok.nh3.internal:8392 -e ALBOK_TOKEN=<token> -- albok-mcp
```

A failure is an `isError` result carrying `unreachable`, `not_albok` or `rejected`; never an empty list.
