Architecture¶
Consumer requirements 3.1 and ADR 0008 are the current product authority; the personal-agent 2.1 scope still applies where it does not conflict with 3.1. The independent personal application has registered sessions, private state, owner management and dedicated background workers. The Astro website remains static and does not hold private state. Personal interfaces use the same governed core as agent interfaces. The product scope says what has shipped.
Casdoor is the external OAuth/OIDC authorization server. Argus API/MCP are resource servers; a separate trusted identity component exchanges upstream codes and maintains encrypted sessions. OAuth API and MCP requests use separate audiences, one configured shared institution, and stable caller IDs derived from issuer plus subject. OAuth subjects are not machine accounts. See MCP for how an AI app signs in.
Argus separates machine access adapters from governed business logic. CLI + Skill, MCP, and REST translate requests, authenticate the caller, and delegate to the same core services. They do not query databases, object storage, or data vendors directly.
AI agent
-> CLI + Skill | MCP | REST
-> machine authentication
-> CommandLineToolService
-> CoreServiceBoundary
1. write-ahead audit start
2. tenant isolation
3. permission check
4. core operation
5. license check
6. schema, evidence, and output-origin validation
7. terminal audit record
-> shared structured result envelope
Argus does not generate an investment judgment. Investment wording and intended independent analysis do not block otherwise permitted fact access. A client AI agent may use lawfully accessible results for unrestricted independent reasoning and downstream output. Data-access controls such as authentication, tenant isolation, permissions, licenses, restricted fields, rate limits, and audit remain mandatory.
Consumer MCP facade¶
src/argus/consumer registers 20 intent tools on the OAuth MCP server only
(requirements 3.1, section 6.2). Each tool calls the existing governed and
personal tools, and every child call is still authorized and audited on its own.
Answers use the consumer-result-v1 envelope.
Consumer reads return only sources that config/consumer_rights.yaml marks
visible. See Consumer tools.
One consumer tool call builds its governed runtime once
(src/argus/core/tool_call_governance.py): the authentication gateway, the rate
limiter, the licence and output-policy services, the access guard and the
boundary. Only these objects are shared. Every child still counts against the
rate limit of its own tool, has the access guard read the account's current
state from the database before and after its work, and has its permission,
licence and output policy evaluated. Access revoked while a tool call runs is
therefore refused at the next child.
The children's audit records and usage rows are kept in memory while the tool call runs and are written in one transaction when it ends, before the answer is returned. If that write fails, the answer is withheld and the call reports a temporary failure. A process that stops in the middle of a tool call leaves no audit record for it and has delivered nothing. Calls outside a consumer tool call (CLI, REST, the machine MCP and the personal tools) write the start record before the operation and the final record after it, as before.
Runtime services¶
| Service | Responsibility | Public exposure |
|---|---|---|
api |
REST, onboarding, skills, health, metrics | API hostname through TLS proxy |
mcp-oauth |
OAuth MCP: the consumer tools only; registry tools are neither listed nor callable | MCP hostname /mcp through TLS proxy |
mcp-machine |
Machine-authenticated MCP at /mcp-machine |
None; the edge answers 404 |
worker |
Governed Celery task execution | None |
beat |
Scheduled retention and vector-index maintenance | None |
| PostgreSQL + pgvector | Persistent domain data, audit, task, and vector records | None |
| Redis | Rate limiting, Celery broker/result coordination, locks | None |
| Object storage | Filing source objects and export artifacts | None |
| Static website | Documentation, search, onboarding, aggregate usage snapshot | Website hostname only; no tool execution |
personal-app |
Private owner pages and account management | Separate registered application origin; private no-store responses |
| Identity/session component | PKCE code exchange, encrypted upstream credentials, registered Argus sessions | Fixed session protocol and trusted service access; separate identity database and secrets |
| Personal notification/export/deletion workers | Durable, fenced jobs in separate queues | None |
Core domains¶
The src/argus/core package contains the business boundary and services for
company/security master data, filings, evidence mapping, events, corporate
actions, market data, neutral metrics, point-in-time snapshots, data quality,
licenses, trust, async tasks, permissions, and audit. Public Pydantic contracts live in src/argus/schemas; persistence
models and repositories live below src/argus/models and src/argus/db.
Data ingestion path¶
Connectors fetch raw source records under a versioned registry definition. The service validates provider, secret, license, allowed use, rate limit, parser version, and field-mapping version before synchronization. Normalizers convert vendor-specific payloads into neutral domain records and source evidence. Filing content can additionally flow through ingestion, parsing, fragmenting, fact extraction, evidence mapping, and optional vector indexing.
Consistency invariants¶
- Equivalent requests through CLI, MCP, and REST preserve fact, evidence, time, quality, license, restriction, and audit semantics.
- Public schema models reject undeclared fields.
- A fact cannot cite an evidence id absent from its package.
- Historical reads exclude facts whose
known_timeis later thanas_of. - Credentials, secrets, and raw sensitive values are redacted from audit output.
- Connector schema, credential, normalization, persistence, and audit validation remain fail-closed. Generic ordinary-read license enforcement defaults off; additional source uses, including export and redistribution, retain their always-on current-rights checks.
- The static website remains independent of the API/MCP runtime lifecycle.
The runtime services table above shows which services the public edge exposes; everything else stays on the internal network.
P1 contract kernel and generated interfaces¶
argus.contracts contains the shared closed envelope and entity, security, ETF,
market, option, filing, and macro payload families. argus.core.tool_registry selects the
input version, output version, payload family, capability, time semantics,
provider coverage, replacement, and exactly three public bindings for every
tool. scripts/generate_interfaces.py materializes those declarations into
checked-in MCP, REST, Skill, and documentation artifacts; runtime CLI remote
routing and MCP contract metadata consume the generated authority directly.
The CLI binding table has no runtime reader, so the generator only builds it in
memory (cli_bindings()) for tests.
The P1 golden contract and live adapter parity test are release gates. Generated
files must pass scripts/generate_interfaces.py --check, and all request/payload
object schemas reject unknown fields.
P3 normalized market domains¶
Options data here, the P4 screener and export, and the P5 feature DAG are advanced capabilities. Under requirements 3.1 they are hidden from consumer discovery and retire in phase 5; see the product scope.
UsEquityEtfOptionDataService is a read-only domain boundary for US security
master/session data, bitemporal ETF snapshots, market observations and corporate
action adjustments, and option contract/chain data. Persistence is normalized by
revision 0032_us_equity_etf_options. ETF visibility requires effective,
publication, and known-time eligibility; adjustments link to actions and a
versioned policy. Provider coverage, delay, missing fields, and license status are
part of each payload. Provider-supplied greeks retain model and input metadata and
never acquire strategy or transaction semantics.
P4 point-in-time query and export¶
PitCatalogService provides the shared Calendar, Instrument, Feature, and Dataset
point-in-time abstractions. Its closed screener DSL enforces field/type/provider/
license/scan limits and stable cursor pagination. The same selected factual rows
feed deterministic Arrow IPC and Parquet partitions whose manifest records schema,
content, partition, time, source, license, adjustment, cache, and dataset identity.
Exports contain no execution engine or performance semantics.
P5 deterministic metrics and feature DAG¶
FeatureDagService is the only derived-value execution path for new interfaces.
It resolves immutable formula id/version pairs from MetricCatalog, verifies PIT
eligibility and evidence for every fact, validates an acyclic bounded graph, and
executes fixed Decimal operators in a stable topological order. Canonical requests
bind cache identity; derived records retain transitive fact, evidence, provider,
as-of, known-at, and formula-version lineage. Multi-source comparison retains all
values and pairwise differences and has no best-source selection field. Public
outputs are structured values and metadata only.
Personal core foundations¶
The independent personal service uses existing OAuth subjects, shared governance
and new additive persistence. Personal state defines stable ownership,
lifecycle, preferences and denial retention. Domain consent intersects each
trusted client's verified scopes with current explicit owner grants.
Confirmation binds server-resolved effects and versions to owner approval and
recent verification for account operations. Registered sessions, CLI/REST/MCP
personal adapters, owner pages, revocation, private workflows and six-language
application flows (ADR 0008) are implemented on these foundations. Sensitive
management stays outside ordinary Agent tools. See the
session protocol and
personal tool contracts.
Private results use per-tool personal-result-v1 schemas; financial children
retain their existing contracts and evidence. Implementation and delivery do not
imply that every source, client or production scenario passed verification.