README · ad958a4e5f4c

a0p — a research instrument

a0p is a research instrument, not a product. It is the public-facing instance of a0 (this codebase), now being prepared for a controlled public release. It explores agent / energy-provider / PCNA dynamics in the open. Public use remains free; code-altering access is restricted to the owner and a small set of explicitly invited collaborators. The instrument is funded by donations and does not solicit subscribers. See PUBLIC_RELEASE.md for the live-release gate instead of assuming that a historical hostname is healthy.

Naming: a0 = the project / runtime / repository (used in contributor-facing material). a0p = the deployed instance of a0 (used in user-facing UI copy and billing). The thing you build is a0; the thing that runs is a0p.

The Agent

ZFAE (a0(zeta fun alpha echo)) is the single persistent agent running on the instrument. Large language models (GPT-5 mini, Gemini 2.5 Flash, Claude Sonnet 4.5, Grok 4 Fast, DeepSeek V4.1 Flash) are treated as energy providers — they supply computational energy for each response but are not the agent itself.

Sub-agents (a0(zeta{n})) can be spawned to fork the PCNA instance, execute in parallel, and merge results back into the primary agent.

Architecture

Three processes compose the runtime:

Browser → Express (:5000) → [proxy /api/*] → Python/FastAPI (:8001)
                          ↘ Vite dev server (:5001)

• Express — Auth, sessions, guest-chat rate limiting. The only public entry point; injects identity and internal-secret headers on every request proxied to Python.
• Python/FastAPI — All AI orchestration, agent lifecycle, billing, and the cognitive engine stack.
• Vite — React frontend (dev only).

Cognitive Engine Stack

a0 pins interdependent-lib@918025e525910eaa3f20141aeb3956f137b248bf, which publishes PTCNA c5fa9a599498f19c8345f2790a0636542dfbc6a1 with UCNS b7b6f35cce69c273860923489a1c8b5372d14eb0. The local PCNA/PTCA/merge algebra has been removed. Integration proves construction, not usefulness, continuous seven-fold geometry, efficacy, or production privacy.

Metadata-Driven Console

The frontend has zero hardcoded tabs. Every Python route module declares UI_META + DATA_SCHEMA; /api/v1/ui/structure aggregates them; the React console renders tabs dynamically.

Access Model

• Public use is free. Donations do not unlock instrument capabilities. Public routes are bounded for privacy, abuse, and provider cost; shared-state mutation remains closed.
• Operator tier — @interdependentway.org accounts are auto-promoted to ws on login.
• Owner-only (“admin”) write endpoints govern actions that mutate shared instrument state: agent state, learning state, system configuration, and module toggles. Per-user CRUD on your own data is not admin-gated. The static contract lives in python/tests/contracts/gating.py.

Contributors will only encounter a 403 if they invoke an instrument-mutation endpoint directly against the deployed instance, which is not part of the documented contribution path. If your work requires an owner-gated endpoint, open an issue first.

Funding

a0p runs on donations. There is no subscription tier and no perk unlocked by donating.

“I don’t have the cash required for 501c3 status, so I have to report it for taxes, but every tax payer is allowed to claim up to five hundred dollars in charitable donations per year without receipts required.”

When the public deployment is healthy, its Pricing page accepts donations. Minimum $5.

The only productized service is the EDCMbone transcript explainer — a one-off paid analysis ($50 for 3 explanations, ~$16.67 each) priced against the operator’s $1,000/hr benchmark.

Local Development

Prerequisites: Node.js 20+, Python 3.12+, PostgreSQL

npm install
pip install -e .

# Start all three processes (Express :5000, Vite :5001, Python :8001)
bash scripts/start-dev.sh

In development scripts/start-dev.sh generates a shared INTERNAL_API_SECRET automatically.

Standalone a0 / Termux with DeepSeek

The standalone run.sh runtime reads the same python/config/providers.json registry as the FastAPI service. With a DeepSeek key present it auto-selects V4.1 Flash through the generic openai-compatible adapter:

export DEEPSEEK_API_KEY="..."
printf '%s\n' '{"task_id":"ds1","input":{"text":"hello"},"tools_allowed":["none"],"mode":"analyze","hmmm":["direct model turn"]}' | ./run.sh

The canonical API model is deepseek-flash. The retired provider choice A0_PROVIDER=deepseek-pro remains a hidden compatibility alias and resolves to the same V4.1 Flash route; it no longer represents a higher-capability tier.

Provider configuration contains only the credential environment-variable name; keys remain in the process environment and are never written to source.

Useful commands

npm run build                      # Production build → dist/
npm run check                      # TypeScript type checking
python scripts/annotate.py         # Re-stamp file N:M ratio annotations

# Static gating contracts (no live server required)
python3 -m pytest python/tests/contracts/route_gating.py python/tests/contracts/gating.py -v

# Full contract suite (requires dev server on :8001 + Postgres)
python3 -m pytest python/tests/contracts/route_gating.py python/tests/contracts/gating.py \
  python/tests/contracts/billing.py python/tests/contracts/chat.py \
  python/tests/contracts/energy.py python/tests/contracts/spawn_executor.py \
  python/tests/contracts/transcripts_explainer.py -v

# Playwright e2e (requires dev server on :5000)
npx playwright install chromium    # first time only
npx playwright test

Required environment variables (production)

Contributing

Standard contribution work — code, docs, tests, evaluation harnesses, architecture diagrams — does not require any elevated in-app access tier. Pull requests go through normal GitHub review.

Areas where help is especially useful:

• LLM provider routing and model gateway design
• Tool-calling and safe tool execution
• Agent memory and context management
• Evaluation harnesses and regression tests
• Documentation and architecture diagrams
• Responsible AI and human-aligned agent behavior

Built and operated by Erin (wayseer00@gmail.com).

Open exact README source