Agience Crystal

Condensation and routing — signal to content type.

Crystal condenses incoming signal into typed content and routes it. As the dispatcher/gateway it maps a request by its content type to one of the chorus tekton services (aria, astra, iris, lumen, ophan, sage, seraph) and carries the gateway concerns: identity, topology, and the MCP client.

It reaches everything over the wire; nothing links it. Origin is called at ORIGIN_URI over HTTP, and the store is injected by the host rather than imported — crystal imports neither.

Install

pip install agience-crystal              # the contract and the ontology driver
pip install agience-crystal[service]     # the gateway that boots — fastapi, uvicorn, httpx, …
pip install agience-crystal[ontology]    # adds the coordinate, and numpy with it

The three are a measured split, not a preference. 23 of crystal's 34 non-test modules import on agience-prism and the stdlib alone; 11 are the ones that serve, and those are what [service] carries. [ontology] is separate again because crystal.ontology.geometry imports numpy at module scope, and a gateway that never computes a coordinate should not install it.

Requires Python 3.11 or newer. The one base dependency is agience-prism, Apache-2.0, whose own base install has no dependencies at all.

Run it

Crystal is two servable surfaces on the same package, and they are different jobs.

The gateway — routes a request by content type to the tekton that owns it:

pip install 'agience-crystal[service]'
CRYSTAL_HOST=127.0.0.1 CRYSTAL_PORT=8085 \
MANTLE_URI=http://localhost:8082 ORIGIN_URI=http://localhost:8080 \
  python -m crystal.main

The host — serves a set of tektons discovered at boot, assembling each with an embodiment:

MCP_HOST=127.0.0.1 MCP_PORT=8086 python -m crystal.host

Bind loopback and put a reverse proxy in front of anything public.

Configuration is the environment, and it is read in two places:

type_registration.py additionally reads CRYSTAL_URI, CHORUS_PUBLIC_URI and AGIENCE_SERVER_HOST_URI when a tekton pushes its types.

A gateway with no Mantle and no Origin still starts; it answers what it can reach.

The embodiment is injected, never imported

import crystal pulls no instrument and no numpy — checked in CI on a bare install, not asserted here. The embodiment that measures arrives from the host at assembly, which is what lets the same crystal run on a full node and on a constrained store. The two test files that do reach an instrument (tests/test_crystal.py, tests/test_embodiment_injection.py) are where the host lives: they assemble a real node, and that reach is test-only by design.

Layout

A tekton owns its own types. Each one ships ui/<top>/<sub>/type.json and pushes it to the gateway's /register endpoint at host startup, signed with a service JWT. Types and tektons are gateway state; the store never sees them.

Where it sits

agience-prism   the contract, dependency-free        crystal depends on it
agience-crystal this repository                      the gateway
agience-ember   the observer unit                    depends on crystal, never the reverse
agience-mantle  the store                            reached over the wire, never imported

Crystal is below ember and mantle in the dependency graph. That direction is what the licence section below is about.

Contributing

See CONTRIBUTING.md. The suite needs two things the package does not — an AGIENCE_BUNDLE_ROOT and an installed agience-ember — and that file says why.

License

Apache-2.0 (see LICENSE and NOTICE).

The permissive licence is load-bearing, and pyproject.toml argues it at length: pip install agience-crystal must not resolve copyleft onto the install path. That is why crystal declares no dependency on ember even though ember sits above it. A dependency that would pull a copyleft package onto the install path is a design conversation, not a dependency bump.