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.

No test here reaches a real instrument either. tests/test_embodiment_injection.py carries a stub embodiment written against prism.embodiment in numpy and the stdlib, and the suite runs on that — an implementation crystal knows nothing about, which is what makes the slot a real slot. The claim that the instrument the host hands over also fits is asserted in agience-ember, which imports crystal; making it from here would have meant importing the repository above this one.

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-mantle  the store                       a SIBLING — neither declares the other
agience-ember   the observer unit               declares crystal, and mantle, and prism

Crystal is below ember: ember declares crystal, and crystal declares nothing of ember. Mantle is beside crystal, not above or below it — reached over the wire and imported by neither side.

Contributing

See CONTRIBUTING.md. The suite needs two public siblings — agience-prism, the package crystal declares, and agience-mantle for one file — and no environment variable, so a fork can run it.

License

Apache-2.0 — see LICENSE and NOTICE.