Metadata-Version: 2.4
Name: a11oy-factory
Version: 0.6.0
Summary: Governed AI distribution compiler: deterministic locks, policy gates, SPDX SBOMs, SLSA provenance, and fail-closed receipts.
Author-email: SZL Holdings <stephenlutar2@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/szl-holdings/a11oy-factory
Project-URL: Source, https://github.com/szl-holdings/a11oy-factory
Project-URL: Issues, https://github.com/szl-holdings/a11oy-factory/issues
Project-URL: Changelog, https://github.com/szl-holdings/a11oy-factory/releases
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: test
Dynamic: license-file

---
title: A11oy Factory
emoji: ⚖️
colorFrom: yellow
colorTo: gray
sdk: docker
app_port: 7860
pinned: false
license: apache-2.0
suggested_hardware: cpu-basic
short_description: Governed AI distribution with verifiable proof.
source_repo: https://github.com/szl-holdings/a11oy-factory
---

# A11oy Factory

<!-- szl:header v1 -->
<!-- Native identity: szl-brand@4309f6fce89179331b0b3ed8c99494e76c5be256; Orbit v2 icon. -->
<p>
  <a href="https://github.com/szl-holdings">
    <img src="https://raw.githubusercontent.com/szl-holdings/szl-brand/4309f6fce89179331b0b3ed8c99494e76c5be256/kit/logos/orbit-v2/suite/szl-icon-32.svg" alt="SZL Holdings — Orbit v2" width="32" height="32" />
  </a>
</p>

**Control before action. Evidence after.**

[Product](https://a-11-oy.com) · [Proof](https://a11oy.net) · [GitHub organization](https://github.com/szl-holdings)
<!-- /szl:header -->

**A11oy Factory is the governed distribution layer for open-source AI
software.** It compiles exact upstream artifacts, target constraints, policy,
evidence, and dependency relationships into a deterministic distribution
bundle.

This is not another model host, container wrapper, or second flagship. It is
the trusted factory between frameworks/models and the CPU, CUDA, XPU, ROCm,
Arm, cloud, edge, and future A11oy/KHIPU hardware that runs them.

## Factory Core v1 — LIVE

LIVE here means the in-repo CLI and library compiler; it is not a hosted
service. The Hugging Face Space is private and runs an older published source
revision, not `main` (see [Surfaces](#surfaces)).

The core now performs real, fail-closed work:

- validates catalog and target-profile contracts;
- resolves dependency closure deterministically and detects cycles;
- enforces immutable source pins, source-host allowlists, license policy,
  evidence requirements, target compatibility, size limits, and network policy;
- emits a content-addressed lock and non-executing build plan;
- emits an SPDX 2.3 SBOM;
- emits an in-toto Statement with SLSA v1 provenance;
- emits an A11oy hash-chained receipt and SHA-256 manifest;
- re-resolves and verifies the whole bundle;
- can explicitly materialize digest-pinned artifacts with streamed SHA-256,
  byte-count enforcement, atomic rename, and no execution.

The compiler is **LIVE**. A generated bundle states
`runtime_certified: false` until hardware execution, current vulnerability
evidence, compatibility testing, and a real cryptographic signer are attached.
Unknown input or missing proof fails closed.

```bash
python -m a11oy_factory distro validate \
  --catalog factory/catalog.json \
  --profile factory/profiles/vllm-cpu-amd64.json

python -m a11oy_factory distro bundle \
  --catalog factory/catalog.json \
  --profile factory/profiles/vllm-cpu-amd64.json \
  --out-dir dist/vllm-cpu-amd64

python -m a11oy_factory distro verify \
  --catalog factory/catalog.json \
  --profile factory/profiles/vllm-cpu-amd64.json \
  --lock dist/vllm-cpu-amd64/factory.lock.json \
  --sbom dist/vllm-cpu-amd64/factory.spdx.json \
  --provenance dist/vllm-cpu-amd64/factory.provenance.json
```

The initial checked-in catalog is a real upstream release snapshot:

| Component | Version | Targets | Integrity |
| --- | --- | --- | --- |
| PyTorch source | 2.13.0 | all initial Linux targets | release SHA-256 pinned |
| PyTorch CPU wheel (CPython 3.12) | 2.13.0+cpu | CPU AMD64 | SHA-256 pinned |
| vLLM CPU wheel | 0.28.0 | AMD64, ARM64 | release SHA-256 pinned |
| vLLM CUDA wheel | 0.28.0 | CUDA 12.9 AMD64, ARM64 | release SHA-256 pinned |
| vLLM XPU wheel | 0.28.0 | Intel XPU AMD64 | release SHA-256 pinned |

Candidate profiles preserve vulnerability state as `UNVERIFIED`; integrity
proof is not misrepresented as a vulnerability scan or runtime certificate.
See [`factory/README.md`](./factory/README.md).

## Install and verify

There is no PyPI release yet (checked 2026-11-06; `publish-pypi.yml` runs its
release gate on Python and packaging changes and publishes only from a GitHub
Release), so install from a checkout. The package has no runtime dependencies and
requires Python 3.11 or newer.

```bash
python -m venv .venv && . .venv/bin/activate
pip install -e .
a11oy-factory distro validate   # defaults to factory/catalog.json + the CPU AMD64 profile

python -m unittest discover -s tests -p "test_*.py"   # Factory Python contracts
python .github/scripts/test_publish_factory_space.py  # Space publisher fail-closed contract
npm ci && npm test                                     # console clean-clone contract (Node 22)
```

## Surfaces

| Surface | State |
| --- | --- |
| GitHub | `szl-holdings/a11oy-factory` · public |
| Hugging Face Space | `SZLHOLDINGS/a11oy-factory` · Docker · private · RUNNING on cpu-basic per the Hub runtime API, observed 2026-11-06 (it was PAUSED when observed 2026-10-13); private, so not publicly reachable · the org pinset (`szl-holdings/.github` `huggingface/PINSET.md`) keeps seven public Spaces and archives the rest as pause + private; this Space is not a keep, so RUNNING is drift from that policy for the owner to resolve (re-pause it or update the pinset) · last published source `ff484bf1` (2026-09-08), behind `main` · the Hub README also carries an estate-card block that was edited on the Hub, not published from GitHub · publishes only by operator dispatch of `hf-sync.yml` |
| Factory Core v1 | LIVE · deterministic metadata distribution |
| Reference profiles | CPU AMD64/ARM64 · CUDA 12.9 AMD64/ARM64 · XPU AMD64 |
| Lyte window | `szl-holdings/lyte-services` · same compiler, not a flagship |
| Merge sink | `szl-holdings/evidence-studio` · one writer |
| Canonical flagship | `SZLHOLDINGS/a11oy` |
| a-11-oy.com production certificate | closed until independent evidence |
| Signing | `UNSIGNED-honest`; tamper-evident hash is not a signature |

## Decision Cell Compiler

The existing Decision Cell Compiler remains fail closed. **Lyte** is the one
admitted structural cell. N1–N27 are named theatres and do not become runtime
LIVE because the distribution compiler can describe them.

| Cell | Title | Cited job | Runtime state |
| --- | --- | --- | --- |
| lyte | Lyte | owner-admitted design-partner cell | STRUCTURAL-ONLY |
| N1 | Serve | vLLM / SGLang / Ollama / TensorRT-LLM | BLOCKED |
| N2 | Graph | LangGraph | BLOCKED |
| N3 | Guard | Llama Guard | BLOCKED |
| N4 | Mosaic | MosaicML / Databricks | BLOCKED |
| N5 | Lattice | SENTRA/YAWAR overlay | BLOCKED |
| N6 | Cover | Guidewire P&C core | BLOCKED |
| N7 | Quant | QuantConnect LEAN | BLOCKED |
| N8 | Title | public property records | BLOCKED |
| N9 | Retrieve | LlamaIndex / Haystack / Letta | BLOCKED |
| N10 | Observe | Phoenix / LangSmith / Langfuse / DeepEval | BLOCKED |
| N11 | Tune | Unsloth LoRA / QLoRA | BLOCKED |
| N12 | Schema | Outlines / Instructor | BLOCKED |
| N13 | Energy | RAPL / NVML joule channel | UNAVAILABLE |
| N14 | Tool | Model Context Protocol | BLOCKED |
| N15 | Memory | Mem0 / Zep Graphiti | BLOCKED |
| N16 | Eval | RAGAS / HELM / Arena | BLOCKED |
| N17 | Mesh | NVIDIA Dynamo / Ray Serve / llm-d | BLOCKED |
| N18 | Route | LiteLLM / OpenRouter / RouteLLM | BLOCKED |
| N19 | Cache | LMCache / Mooncake / GPTCache | BLOCKED |
| N20 | Voice | LiveKit / Cartesia / Deepgram | BLOCKED |
| N21 | Sandbox | Daytona / E2B | BLOCKED |
| N22 | Identity | SPIFFE / SPIRE / NHI policy | BLOCKED |
| N23 | Rails | NVIDIA NeMo Guardrails | BLOCKED |
| N24 | Browser | Playwright / Stagehand / Browserbase | BLOCKED |
| N25 | Policy | AWS Cedar / Open Policy Agent | BLOCKED |
| N26 | Inference | wrapped NVML/RAPL measurement | REPORTED, BLOCKED |
| N27 | Train | receipted GPU train gate | UNAVAILABLE |

```bash
python -m a11oy_factory compile --cell lyte
python -m a11oy_factory compile --cell N1
python -m a11oy_factory roadmap
python -m a11oy_factory act --cell N22 --payload '{"agent":"counsel"}'
python -m a11oy_factory search --q vllm
```

## Proof boundary

| Claim | State |
| --- | --- |
| Deterministic catalog/profile resolution | LIVE |
| Immutable release-asset pins | LIVE |
| License/evidence/target policy | LIVE |
| SPDX and SLSA documents | LIVE |
| Explicit artifact byte verification | LIVE when materialization is invoked |
| Vulnerability clearance | UNVERIFIED in candidate profiles |
| Runtime compatibility on target hardware | NOT_CERTIFIED |
| Production cryptographic signature | UNAVAILABLE |
| Energy measurement | UNAVAILABLE without readable RAPL/NVML |
| Λ uniqueness | Conjecture 1 OPEN |

Formulas never grant authority. Metadata integrity is not runtime safety.
`UNSIGNED-honest` is not Cosign, Fulcio, Rekor, or an ATO.

## Source quality gate

The always-on pull-request gate installs exactly `package-lock.json` with
`npm ci`, runs `npm test`, starts the real local Vite server, checks the live
`/__app-env` contract with `npm run check:auth`, and then lints and typechecks
the application and executes its production build. A stale lockfile is a hard failure; CI never falls back to a
mutable install.

`npm test` is the clean-clone contract. It runs the checked-in, autonomous
Node and TypeScript suites that do not depend on the app-builder authoring
environment, including the auth-invariant and environment-wrapper units.
The Python gate separately runs the provider-publisher and Factory suites.
`npm run test:template` deliberately exposes the broader template
suite. That suite expects generated `public/__grok` assets, `.grok/skills/og`
documentation, the shipped `.grok/app-env.json`, and symlink privileges. It is
therefore an authoring-environment check, not a clean-clone success claim; its
failures must be repaired or reported, never relabeled as a passing CI gate.

## Hugging Face publication boundary

Merging `main` does not publish the Space. Publication is an explicit
`workflow_dispatch` operation in `hf-sync.yml` and requires the exact lowercase
40-character SHA of the current `main` commit. The workflow checks out that
commit, fetches current `origin/main`, and fails closed unless all three SHAs
agree. The publisher repeats the Git HEAD/current-main comparison immediately
before upload, embeds the SHA in the Hugging Face commit message, and generates
a deterministic provenance record that the rebuilt runtime must expose from
`/healthz`. Deployment verification fails until that runtime SHA and a final
current-main readback agree. Provider commits are compare-and-swapped against
the observed prior Space revision and delete stale files so publication is an
exact mirror rather than an accumulating overlay.

The workflow first requests a Hugging Face Trusted Publisher (OIDC) token scoped
to `spaces/SZLHOLDINGS/a11oy-factory`, through the organization credential
selector pinned by commit. Its only fallback is the uniquely named
`HF_FACTORY_PRODUCTION_TOKEN` secret from the `hugging-face-production` GitHub
environment; no repository-wide Hugging Face secret is offered to the job. The
uploaded proof includes the selector's report, which names the credential
source that was used without recording any token. That environment must exist, restrict deployment to `main`, and
require an explicit operator review; a missing or unprotected environment is a
release blocker. In a solo build, that review is an operator authorization and
is not mislabeled independent approval. A successful source PR or merge is not
deployment proof; the workflow separately verifies the resulting Space and
uploads the runtime evidence artifact. A blocked verification writes a
sanitized failure receipt, and the workflow retains that receipt even though
the verification step exits nonzero.

Estate on Hugging Face: models, datasets and Spaces are published under the [SZLHOLDINGS](https://huggingface.co/SZLHOLDINGS) org.
