Contributing a pack from your own package
An external group can ship packs, bundles and connectors as an ordinary Python package. Nothing lands in the archi repository. ADR 0002 section 4.4 is the design; Pack and bundle format is the reference for the manifest files. This page says what your package must contain and how to test it.
What the package declares
-
Entry points. One per directory you ship:
toml [project.entry-points."archi.packs"] mywg = "mywg_packs:packs_dir" # returns a directory of <pack>/pack.yaml [project.entry-points."archi.bundles"] mywg = "mywg_packs:bundles_dir" # optional: a directory of <bundle>/bundle.yamlThe value is a callable returning the directory (or the directory itself). The entry-point name (
mywg) is the provider label users see. -
Pack manifests, one
packs/<name>/pack.yamleach, valid against the published schema (archi bundles validate <dir>). Package the directories as data files in your wheel. Rules that bite external packs:- pack names are global: two providers with the same name are both reported
as a problem, so prefix yours (
mywg-...); - a pack that needs a credential sets
needs_credentials: trueand names environment variables incredentials; never a value; - every context-pack source has a
freshnessentry; - automation packs cannot ask for a level above L2.
- pack names are global: two providers with the same name are both reported
as a problem, so prefix yours (
-
Connectors. A connector is the code that pulls one external system into the graph. It is an okg
SourceAdapter(okg's mechanism name), referenced from a source template in the pack bymodule:andclass::yaml mywg-tickets: module: mywg_connectors.tickets class: TicketSource ownership_id: ${deployment_name}.mywg-tickets admission_policy: { ... } # producer authority, output_signature, as okg requiresYour package must be importable in the environment where
okgruns, so list okg as an install-time requirement of the deployment, not of your wheel (okg is the host environment; archi does not declare it either). The adapter contract (change probes, producer authority, admission mode, record identity) is okg's, and okg alignment lists the interface archi relies on.
Versioning
- Each pack and bundle has its own
version(MAJOR.MINOR.PATCH). Raise MAJOR when a source's output signature, record identity or a question id changes: an instance'sarchi.lockrecords the selection andarchi diffreports drift. - Each bundle states the okg range it supports in
okg:(PEP 440, for example">=0.6.0,<0.7"). A pack inherits the check through the bundles that use it. - The wheel's version is yours. Pin the range of
archi-kbyou were tested against in your owndependencies.
What users see
With your wheel installed in the same environment as archi:
$ archi bundles list
...
mywg-tickets 0.1.0 (context, needs credentials) [mywg (mywg-packs 0.1.0)]
The bracket is the provider: the entry-point name and the distribution and
version that registered it. archi bundles list --json has it as provider.
Use archi render --bundle B --with mywg-tickets --instance DIR or
archi add mywg-tickets --instance DIR to install it.
How to test it
archi bundles validate path/to/packsmust report no problem.archi bundles list --jsonmust show your packs with your provider label and an emptyproblemslist. A broken entry point is listed, not fatal.archi render --bundle <your bundle> --instance <tmp>thenokg install --profile <name> --dry-run --json --non-interactive ...must reportdry_run_okwith no blockers.- Publish against a real graph database in your own CI, the way
archi initdoes.
archi's own copy of steps 2 and 3 runs against a fixture package,
python/tests/bundles/fixtures/thirdparty/archi_fixture_packs/, built into a wheel
in python/tests/bundles/test_packaging.py. Copy that package as a starting point.
Bringing an MCP server instead
If what you have is a live tool and not ingestion, you do not need a pack:
declare it under mcp_servers: in the instance's archi.yaml and
archi connect registers it next to the instance server
(Connecting other agents).