Server CLI reference

Package: piighost-api

piighost-api is the command line of the companion server. serve starts the HTTP server. The dataset commands build and score a detection dataset from observation traces.

piighost-api serve [--config SOURCE] [--host HOST] [--port PORT] [--log-level LEVEL]
piighost-api dataset extract --output FILE [--since DATE] [--until DATE] [--mode MODE] [--limit N]
piighost-api dataset metrics --input FILE [--output FILE] [--output-format FORMAT] [--match-mode MODE] [--iou-threshold FLOAT] [--source SOURCE]

The server requires Python 3.12 or later and piighost>=2.0,<3. Its extras add optional features:

pip install "piighost-api[gliner2,observation]"

piighost-api serve

Builds the pipeline once and serves the API endpoints with uvicorn, in a single process.

piighost-api serve --config catalog:piighost/support-en --host 0.0.0.0 --port 8000

• With neither --config nor PIIGHOST_CONFIG, the command prints Missing --config or PIIGHOST_CONFIG. with a usage hint and exits 1. A file path that does not exist exits 1 with Configuration file not found:.
• A catalog reference loads the whole configuration the piighost catalog publishes under that name. A reference pinned to a commit is fetched on the first start and read from the disk cache afterwards.
• A configuration that declares no [memory] section is served with the in-process memory, in_memory. Its threads live in the server process, so every instance holds its own. Several instances behind a load balancer need a shared redis or sqlalchemy memory, see Multi-instance deployment.
• Any top-level section can be overridden with a PIIGHOST_ variable holding a JSON object, as for a file, see Environment overrides. PIIGHOST_MEMORY thus adds a shared memory to a catalog configuration. The memory in the example below needs piighost[crypto] for its cipher.
• Without a key in an API_KEY_ variable, the server refuses to start unless PIIGHOST_ALLOW_ANONYMOUS is set.

export PIIGHOST_MEMORY='{"type": "redis", "url": "redis://redis:6379/0", "hasher": {"type": "argon2"}, "cipher": {"type": "aesgcm"}}'
piighost-api serve --config catalog:piighost/support-en

Environment variables

The pipeline reads its own secrets (PIIGHOST_HASH_PEPPER, PIIGHOST_CIPHER_KEY, PIIGHOST_DATABASE_URL and MISTRAL_API_KEY). PIIGHOST_CATALOG_URL names a private catalog. These variables are listed in the TOML reference. The other OTEL_* variables, headers included, are read by the OpenTelemetry exporter itself, see Observation.

The Docker image reads four more, listed in Deploy a production pipeline.

piighost-api dataset extract

Reads traces from Langfuse and writes one JSONL record per trace. It needs the dataset extra and LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY, read from the environment or from a .env file in the working directory. Without them, it exits 1.

piighost-api dataset extract --output dataset.jsonl --since 2026-09-01 --limit 1000

A trace without input text, or a model trace without its piighost.detect child, is skipped. The command ends with Wrote N records to FILE (M skipped).

{
  "text": "Hi Jane Doe, from Acme in Boston",
  "entities": [[3, 11, "PERSON"], [18, 22, "ORGANIZATION"], [26, 32, "LOCATION"]],
  "model_entities": [[3, 11, "PERSON"], [18, 22, "LOCATION"]],
  "labels_universe": [],
  "source": "hitl",
  "trace_id": "...",
  "session_id": "...",
  "created_at": "..."
}

piighost-api dataset metrics

Scores the model against the reference of a JSONL file written by dataset extract, label by label. It needs no extra.

piighost-api dataset metrics --input dataset.jsonl

On the record above, the table reads:

label                    tp     fp     fn      P      R     F1
--------------------------------------------------------------
LOCATION                  0      1      1   0.00   0.00   0.00
ORGANIZATION              0      0      1   0.00   0.00   0.00
PERSON                    1      0      0   1.00   1.00   1.00
--------------------------------------------------------------
macro avg                 -      -      -   0.33   0.33   0.33
micro avg                 -      -      -   0.50   0.33   0.40

Label confusion (model -> human, same span):
  LOCATION -> ORGANIZATION: 1

tp counts a model span the reference holds, fp a model span it lacks, fn a reference span the model missed. P, R and F1 are the precision, the recall and their harmonic mean. The confusion section lists the spans where model and reference agree on the offsets and differ on the label.

See also

• API endpoints: every route the server serves.
• Deploy a de-identification API: a first server, step by step.
• CLI: the piighost command of the library.