althing-registry

Curated index of community-authored packs for Althing, a lightweight LLM-agnostic research harness for synthetic focus groups.

Looking for ai-eval-buyers, product-research, developer, recruiters-talent, or the other named persona packs? Those are SDK builtins that ship inside pip install althing — they are deliberately not registry entries and won't appear in default.json. After installing, they resolve by name with no import step (althing pack list shows all 14). See the Althing README's "Packs: Builtin vs Registry" section for the full builtin list. This registry indexes community-authored packs only.

Canonical source for community packs

This repository is the canonical source of truth for community-authored Althing packs. The althing CLI resolves community pack IDs against default.json in this repo (pack search, pack import gh:...).

Concretely:

• Builtin packs = shipped in the Althing wheel. First-class, maintained in the Althing repo, immediately resolvable by name after pip install althing. Never listed here.
• Registry (this repo) = community catalog. Stable pack IDs, reviewed YAML, and the manifest at default.json listing every community pack agents can import.
• Althing CLI / MCP = resolver. For community packs, fetches the manifest, looks up the requested pack ID, and pulls the YAML at packs/<pack-id>/althing-pack.yaml. Once imported, a community pack resolves by name like a builtin.

Builtin and registry namespaces are kept disjoint (Althing warns on collisions at import time); if a community pack ID here somehow shadows a locally imported copy, the registry entry wins for re-imports.

What this is

A thin, human-reviewed catalog. The root default.json is the manifest Althing fetches at runtime to power pack search and pack import gh:.... There is no runtime here — only JSON, a schema, and a PR workflow.

How discovery works

1. A pack author drops a althing-pack.yaml under packs/<pack-id>/ in this repo (see CONTRIBUTING.md).
2. They open a submission issue, then a PR adding the pack directory and the regenerated default.json.
3. A reviewer checks the submission criteria in CONTRIBUTING and merges. added_at is stamped automatically from the pack directory's first commit by scripts/build_registry.py.
4. Althing clients fetch https://raw.githubusercontent.com/DataViking-Tech/althing-registry/main/default.json (cached 24h) to surface the pack via althing pack search and to resolve registered gh:owner/repo imports.

Pack IDs as a stable contract

A pack's id is the agent-facing primary key. Once a pack lands in default.json, its id is treated as a stable, public identifier that downstream tooling and agents may pin to indefinitely.

Three rules keep IDs stable:

1. Slug shape. IDs must match ^[a-z0-9]+(-[a-z0-9]+)*$ (lowercase kebab-case). Enforced by schema/default.schema.json.
2. Directory == ID. The pack lives at packs/<pack-id>/althing-pack.yaml and the directory name MUST equal the YAML's top-level id:. Enforced by scripts/build_registry.py.
3. No silent renames. Changing a pack's id is a breaking change for every consumer that pinned it. Rename = remove + re-add under the new ID, with the old ID deprecated via the pack-removal flow.

Versioning lives on the pack YAML's top-level version: field and is mirrored to the registry entry's version field. Agents that need content-stability beyond ID may pin against a version (or commit SHA, via the schema's optional ref field) — see schema/default.schema.json.

Resolving packs as an agent or downstream tool

Agents and integrations consuming this registry directly should:

1. Fetch the manifest: https://raw.githubusercontent.com/DataViking-Tech/althing-registry/main/default.json — JSON Schema at schema/default.schema.json. Cache for up to 24h.
2. Filter by kind to pick the right pack family:
   • kind: persona — persona panels (ICPs, demographic cohorts, vertical buyer sets, stress-test probes). All v1 packs are personas.
   • kind: instrument — reserved for future survey/measurement instruments. Not populated in v1; downstream tooling should treat an empty instrument set as expected.
3. Resolve the YAML at the entry's repo + path (default main branch unless an entry sets ref). The full URL pattern is https://raw.githubusercontent.com/<repo>/<ref|main>/<path>.
4. Match by id when a user or upstream config names a specific pack (e.g. althing pack import icp-althing). IDs are stable; names and descriptions are human-readable hints, not lookup keys.

The current pack catalog (IDs, kinds, descriptions, calibration counts) is always default.json at the repo root — read it directly rather than scraping this README, which may lag the manifest.

Manifest shape

See schema/default.schema.json for the authoritative JSON Schema. Validation runs in CI on every PR.

Each entry may also carry an optional calibration_count integer summarizing how many calibration runs the pack has declared on its calibration: list. Packs without calibration runs omit the field — "uncalibrated" is a valid state for ICP, vertical, and stress-test packs. See CONTRIBUTING.md → Calibration for the field convention and JSD interpretation guide.

Adding a pack

1. Drop your pack YAML at packs/<pack-id>/althing-pack.yaml (one directory per pack; the directory name must equal the pack's id:).
2. Regenerate the registry index locally:

   pip install pyyaml jsonschema althing
   python scripts/build_registry.py
   

   The script walks every packs/*/althing-pack.yaml, validates it against althing's persona-pack schema, and rewrites default.json deterministically (stable sort, canonical JSON).
3. Commit both the new pack and the regenerated default.json in your PR.

CI runs python scripts/build_registry.py --check on every PR. Any pack that fails persona-pack validation or any PR whose default.json is stale relative to its packs/ tree will fail the registry-build status check.

Removal

Authors may request takedown via the pack removal issue template.