agience-crystal

Agience Crystal

Condensation and routing — signal to content type.

Crystal condenses incoming signal into typed content and dispatches it. As a gateway it maps a request by its content type to the upstream service that owns it, and carries the gateway concerns: identity, topology, the type registry and the MCP client. Everything it depends on at runtime is reached over the wire and configured by URI.

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

Requires Python 3.11 or newer. The one base dependency is agience-prism.

The split follows what each module imports: the base install is the contract, [service] is what crystal.main and crystal.host need to serve, and [ontology] is separate again because crystal.ontology.geometry imports numpy at module scope.

Run it

Two servable surfaces on the same package.

The gateway — routes a request by content type to the service 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 personas 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. A gateway whose upstreams are unreachable still starts, and answers what it can reach.

Configuration

The injected embodiment

The embodiment that measures arrives from the host at assembly time, through crystal.ontology.driver.set_default_store_provider and the prism.embodiment contract. The same crystal therefore runs against a full node and against a constrained store, with no import of either.

tests/test_embodiment_injection.py runs the suite against a stub embodiment written in numpy and the stdlib, and holds the base install to that allow-list — so the slot stays a real slot and import crystal stays free of the measuring stack.

Types

A content type is a directory: type.json, plus optional schema.json, behaviors.json, preview.json and handlers/. src/types/ holds the builtin skeletons — text, image, audio, video, application — as repository content read by a test, rather than as wheel payload, since nothing loads them from the package at runtime.

An upstream owns its own types and pushes them to the gateway's /register endpoint at startup, signed with a service JWT. Types and personas are gateway state.

Layout

Contributing

See CONTRIBUTING.md, which lists what the suite needs. It reads the environment for nothing, so a fork can run it once those packages are installed.

Security issues: email connect@agience.ai rather than opening a public issue.

Licensed under Apache-2.0 — see LICENSE and NOTICE.

Declaration of generative AI use

The author used Anthropic's Claude Opus (versions 4.8, 5, and 5.5) in the preparation of this work. Its contribution was to write code, and to generate and validate content. The ideas, the construction and the claims are the author's. No other generative AI tool was used. The author reviewed and edited all output and takes full responsibility for the content of this publication.