Packs¶
The pack format primitives. For the conceptual model and the authoring workflow see the Authoring packs guide.
The shipped reference pack is Diligence.
Pack declaration¶
A frozen bundle of pack contents.
Equality and hashing are by (name, version) — NOT by deep field comparison. Behaviors and tools are dataclasses (not hashable); full structural equality would not work and isn't what users care about. The identity that matters is "is this the same pack name and version" — that's what idempotent loading hinges on.
prompt_manifest()
¶
The pack.loaded payload's prompts block. Maps prompt
name to {"version", "hash"}. CONTRACT v0.9 #10.
A typed object the pack contributes.
schema is a Pydantic BaseModel subclass. When the pack is
loaded, graph.add_object(name, data=...) validates against it.
Validation applies only to objects created AFTER the pack loads
(CONTRACT v0.9 #5).
A typed relation the pack contributes.
source_types and target_types are tuples of object type names;
empty means "any".
A policy declared by a pack.
requires_approval: tuple of object type names whose add_object
is gated until runtime.approve(...) is called.
A versioned, content-hashed prompt.
version is the declared human-readable version (for changelogs
and operator messages). content_hash is the SHA-256 of the body
truncated to 16 hex chars; this is the replay contract (the
hash, not the version — see CONTRACT v0.9 #10).
Bases: BaseModel
For packs with no configurable settings. Pydantic model so it matches the rest of the settings API.
Discovery¶
Enumerate installed packs via the activegraph.packs entry
point group. Cached per process; call clear_discovery_cache()
to force a re-scan.
Reset the cached entry-point scan. Tests that install packages dynamically need to call this; normal usage does not.
Scan a directory of *.md prompt files with TOML frontmatter.
Each file MUST start with:
---
version = "1.0.0"
name = "optional_name" # defaults to filename without .md
---
<body>
Returns a tuple of PackPrompt sorted by name. Content hash is
computed over the body (everything after the second --- line
and one separating newline), exactly as it will appear at runtime.
Errors
- missing/malformed frontmatter -> PackPromptLoadError
- missing required
versionfield -> PackPromptLoadError - duplicate prompt name -> PackPromptLoadError
- I/O failure -> PackPromptLoadError