Questions that come up when evaluating, running, or contributing to AtOM. For a
symptom-and-fix table see the Troubleshooting section of
README.md; this document answers the why questions that table
does not.
A platform for the whole life of a specification change. An idea becomes deep research, a product canvas, requirements, a technical specification and XSD schemas; those go to the organisations that must implement them; their questions come back; code is generated against a real repository; and the result is certified. Each stage is an AI agent, and an evaluation gate sits between stages so a stage advances because its output passed checks, not because a model returned text.
It was built for one — a central body publishes a change and many banks
implement it — and some generated prose is still payments-specific. Domain
vocabulary is moving behind a pluggable domain pack (DOMAIN_PACK, default
network). The interface is backend/app/core/domain/contract.py and
backend/app/packs/network/ is a complete worked example. A test enforces that
app/core/** never imports app/packs/**, so the separation cannot rot
quietly.
No, and this is deliberate. PHASE_B_RUNNER_MODE defaults to demo, which is
fully simulated and says so in every log line it emits. build compiles the
target repository and stops. ssh and local run an operator-supplied script.
A human opens the merge request in every mode.
atom-partner-platform
is the receiving side — the reference implementation partner organisations fork
to consume changes over A2A and plug in their own agents. It is a separate
repository and a separate stack, and reaches this platform as an authenticated
A2A client. Nothing about it needs to be deployed here.
Yes, and this catches people out. The root .env is what Docker Compose
interpolates into docker-compose.yml — it holds POSTGRES_PASSWORD,
REDIS_PASSWORD and CERTSIM_INTERNAL_TOKEN, none of which have defaults.
backend/.env is a different file, handed to the backend, celery and
celery_beat containers as their environment. Copy both examples.
Three services attach to certagent_cert-net, an external network owned by a
certification stack that lives elsewhere. Compose expects it to exist already.
docker network create certagent_cert-net is enough for a local stack — it can
stay empty.
nginx resolves upstream DNS once at startup, so a recreated container gets a new
address and nginx keeps proxying to the old one. docker compose restart nginx.
This is the single most common false alarm in this stack.
app/ is baked into the image. Live editing needs a docker-compose.override.yml
bind mount, which is gitignored and absent by default. backend/tests/ is baked
too — after editing a test, rebuild or docker cp the file in.
The full stack is Docker-only in the supported path. docker-compose.db.yml
runs just Postgres and Redis in containers if you want to run the application
natively against them.
Eight in the default stack. The reranker is behind a Compose profile and off
by default — it costs about 2 GB of image and 1.5 GB of RAM for a feature
disabled by default. Start it with docker compose --profile reranker up -d and
set USE_RERANKER=true.
Authentication is layered — TLS, Bearer JWT, HMAC envelope, mTLS, CIDR
allow-list, rate limit — and each layer fails differently. Check the
a2a_messages audit row for the exchange first; it records which layer refused.
The most common cause is that the two sides' hmac_signer.py have diverged.
Each service builds from its own Docker context, and a Dockerfile cannot COPY
outside its context, so an installable package at the repository root cannot
reach any of these images. The copies are therefore generated:
packages/a2a-core/ is the one editable source, scripts/ci/sync-a2a-core.sh
writes the copies, and CI fails on drift. Editing a copy is wasted work — the
next sync overwrites it.
Leave Message.task_id empty on a first send. Setting it means continue this
existing task, so the remote side is being asked to continue something it has
never heard of, and it answers exactly that. This is the most-repeated mistake
against this wire, and it reads like a server bug.
No. Neither repository's CI can see the other's copies, so a one-sided change leaves both test suites green while live calls are rejected. Wire changes are a coordinated release across both repositories.
Model choice is per-agent purpose, resolved through
backend/app/core/llm_router.py — REASONING, ROUTING or UTILITY — never a
model string pinned inside an agent. An unmapped agent name defaults to
REASONING, so a missed mapping costs money rather than quality.
Five. LLM_PROVIDER accepts anthropic, openai, gemini, ainxt or
ollama, and defaults to anthropic. (claude is still accepted as a
backward-compatible alias for anthropic.) Every call goes through
backend/app/core/llm.py, which dispatches on that setting; agents never call a
vendor SDK directly.
ainxt is not a hosted service you can sign up for — it is the adapter for an
OpenAI-compatible gateway you run yourself, pointed at by AINXT_BASE_URL.
Switching provider is a one-line change for text generation, but it is not true that every feature works on every provider. The matrix below is the honest answer; read it before choosing.
All five providers are first-class for text generation. Two capabilities are
built on the Anthropic /v1/messages tool-use protocol and are reachable only
on providers that speak it.
| Capability | anthropic |
openai |
gemini |
ollama |
ainxt |
|---|---|---|---|---|---|
Text completion (call_llm) |
✅ | ✅ | ✅ | ✅ | ✅ |
Streaming (stream_llm) |
✅ | ✅ | ✅ | ✅ | ✅ |
| Structured output | ✅ | ✅ | ✅ | ✅ | ✅ |
| Document generation, retrieval, evaluation | ✅ | ✅ | ✅ | ✅ | ✅ |
| Agentic code generation (native tool loop) | ✅ | ❌ | ❌ | ❌ | |
| Figure/diagram understanding (vision) | ✅ | ❌ | ❌ | ❌ |
ainxt supports the tool loop and vision only when
AINXT_COMPAT_MODE=anthropic. In its default openai mode it behaves like
openai in this table.
Structured output uses forced tool-use where the protocol supports it and prose-JSON parsing everywhere else; both paths are tested.
What happens when a capability is missing. Agentic code generation refuses at preflight, naming the provider and the setting to change — before it clones a repository or builds a workspace. Vision logs one warning per process and skips the figures, so an upload still succeeds but embedded diagrams do not reach the pipeline and the generated document is correspondingly thinner.
Output budgets are clamped per model, not per vendor. Agents request an
ambitious max_tokens; app/core/tokens.py resolves the real cap for the
active model (falling back to the provider's) and clamps to it. A model with a
16k output cap no longer hard-fails on an agent written against a 64k one.
Context windows resolve the same way — add unlisted models to
_MODEL_CONTEXT_WINDOW so budgeting stays accurate.
Embeddings are a separate concern and currently require Ollama regardless of
LLM_PROVIDER.
Per-run token budgets with hard caps, per-provider circuit breakers, bulkheads limiting concurrent LLM calls, explicit timeouts, and a global cap on concurrent agentic runs. A rejected run is reported as rejected rather than silently truncated.
Two reasons. A prompt loaded from a writable store is an injection surface — whoever can edit the row rewrites the model's instructions for every later run. And a prompt in git is a reviewable diff with an author. Note the trailing-newline rule: files end with exactly one and the loader strips exactly one, because prompt caches key on exact prefix bytes and a stray byte silently costs cache hits on every request.
Privately, per SECURITY.md. Never in a public issue. The GitHub
issue templates route you there.
Yes, by design — it processes specifications and partner correspondence that can
contain account references and free text. Two tiers of control: a runtime
redaction filter, and a design-time classification in the wire protocol where
each A2A message type is marked as PII-bearing or not, with a required rationale
for every type and a test that fails CI if one is missing. carries_pii() fails
closed: an unrecognised task type is treated as PII-bearing.
Mitigated, not solved. Ingested specifications and uploaded documents are
treated as data rather than instructions, and XML is defused against XXE. It
remains an active risk with untrusted input — see SECURITY.md.
Brute-force protection. Set CAPTCHA_ENABLED=false in backend/.env for a local
loop, and leave it on anywhere others can reach.
Sign off every commit (git commit -s — DCO, not a CLA; PRs without it cannot
be merged), use Conventional Commits, and run the three gates in
README.md step 8. See CONTRIBUTING.md.
A CLA would let the copyright holder relicense contributed code later, but it needs legal administration and is a documented deterrent to casual contributors. If a relicensing need arises it will be negotiated with contributors rather than pre-empted.
Six things fail quietly rather than loudly, and the pull-request template lists
them as a checklist: editing a vendored copy of the wire code instead of
packages/a2a-core/; changing a prompt's trailing newline; reading a setting
with getattr when the field is not declared on Settings (which is
extra="ignore", so the env var is silently dropped); a migration that is not
inspector-gated; a new agent with no llm_router mapping; and domain vocabulary
added to core/ instead of a pack.
MIT contains no trademark clause at all, so it conveys no trademark rights. The
names, logos and marks are reserved under ordinary trademark law and
TRADEMARKS.md is the only place that position is stated.