AtlasOS

Macro-financial monitoring for reproducible portfolio risk, audited decisions, and cited institutional reports.

AtlasOS is an institutional macro-financial monitoring platform. It turns frozen macro snapshots and portfolio inputs into deterministic risk analyses, decision reports, and traceable narratives. The system is designed around one operating rule: every number must be reproducible, every claim must cite its source, and every decision must leave an audit trail.

Product Screenshots

Executive Overview

Decision Reports

Macro Monitor

What AtlasOS Does

AtlasOS combines deterministic quantitative engines with a governed reporting layer. The LLM, when enabled, does not calculate figures. It can plan and narrate, but every numeric output comes from the engine artifacts and every numeric claim is citation-checked before it reaches the user.

Capability	Description
Portfolio impairment analysis	Joint portfolio impairment simulation with macro, sector, company, and valuation multiple factors.
Macro monitor	Current regime, stress index, indicator trends, alerts, and state-conditioned reference scenarios.
Decision reports	Persisted institutional memos with severities, actions, drivers, figures, and citations.
Cited narratives	Optional LLM-generated explanations constrained to citable engine values.
Audit trail	Snapshot hashes, artifacts, API runs, reports, and agent traces are persisted.
Graceful degradation	With no LLM key, AtlasOS still runs deterministic engines and cited template narratives.

Operating Principles

1. Deterministic engines produce all figures.
2. The LLM never performs calculations.
3. Analyses run on identified, hash-verified snapshots.
4. Reports cite exact artifact values, not vague sources.
5. Narration failure never blocks the underlying numbers.
6. Published validation results are shown as measured, including limitations.

System Architecture

flowchart LR
    A["Macro data and portfolio inputs"] --> B["Snapshot store"]
    B --> C["Engine registry"]
    C --> D["Impairment engine"]
    C --> E["Macro monitor engine"]
    D --> F["Artifact store"]
    E --> F
    F --> G["Report builder"]
    G --> H["Decision memo"]
    F --> I["Agent service"]
    I --> J["Cited narrative"]
    H --> K["React interface"]
    J --> K

Loading

AtlasOS separates platform infrastructure, domain engines, agent orchestration, and user interfaces:

Layer	Responsibility
atlas.platform	Contracts, snapshots, artifacts, database models, settings, queue, and execution runtime.
atlas.domain	Macro ingestion, impairment engine, macro monitor, validation, and report models.
atlas.agent	Planning, narration, citation validation, LLM abstraction, and trace storage.
atlas.interfaces	FastAPI application, API-key auth, CLI operations, worker process, and static UI hosting.
frontend	React/Vite institutional interface and server-side deployment proxy.

Analysis Lifecycle

sequenceDiagram
    participant User
    participant API
    participant Snapshot as Snapshot Store
    participant Engine
    participant Artifacts
    participant Report
    participant UI

    User->>API: Submit analysis request
    API->>Snapshot: Resolve frozen snapshot
    API->>Engine: Execute deterministic model
    Engine->>Artifacts: Publish CSV and JSON outputs
    API->>Report: Build cited decision memo
    Report->>Artifacts: Resolve exact values
    UI->>API: Display run, report, citations

Loading

Validation and Evidence

AtlasOS includes a reproducible validation workflow for the macro crisis classifier and model benchmarks. The current validation report covers walk-forward testing, target sensitivity, probability calibration, false-alert burden, and feature influence.

Artifact	Location
Validation report	docs/validation_report.md
Agent eval record	docs/agent_evals.md
Architecture decisions	docs/DECISIONS.md
Known limitations	docs/limitations.md

Model Evidence

Security and Governance

AtlasOS is built for a controlled institutional environment:

Control	Implementation
API authentication	API keys with read and run scopes. Plaintext tokens are shown once and stored as hashes.
Server-side secrets	Browser clients do not store Atlas API keys. Vercel deployments use a server-side proxy.
Request hardening	Security headers, maximum body size, and dependency-free rate limiting are included.
Data integrity	Snapshots use content identity and parquet-byte integrity checks.
Traceability	Runs, reports, artifacts, and agent traces are persisted for later review.
LLM containment	LLM clients receive capability catalogs and citable values, not raw snapshot tables.

Browser authentication has two supported paths. A Vercel deployment calls the same-origin /api/atlas/* proxy, which injects its server-side API key. An explicit local demo bootstrap issues an HttpOnly, SameSite=Strict cookie; the plaintext key is never returned to JavaScript. Direct API clients continue to authenticate with X-API-Key.

Deployment Model

AtlasOS can run as a local evaluation instance, a containerized backend with Postgres and Redis, or a split deployment where the frontend is served separately and calls the Atlas API through a server-side proxy.

Python dependencies are resolved in the committed uv.lock. CI and production images use uv sync --locked, so a dependency release cannot silently change a previously validated build. scripts/compose_e2e.py exercises the running Postgres, Redis, API and worker stack. It requires an isolated COMPOSE_PROJECT_NAME; CI uses atlas-ci so validation data and volumes never overlap with a developer stack.

React is the canonical browser interface. The Docker image builds it in a Node stage, packages it with the Python application, and serves it at /. The former vanilla interface remains available at /legacy only as a rollback surface.

Version tags (v*) publish the validated production image to ghcr.io/<owner>/<repository> with semantic-version, commit SHA and latest tags. The same workflow can be run manually when an operator needs a SHA-tagged image without creating a release tag.

flowchart TB
    U["User browser"] --> V["React frontend"]
    V --> P["Server-side proxy"]
    P --> A["Atlas FastAPI"]
    A --> Q["Queue"]
    Q --> W["Worker"]
    A --> DB["Postgres or SQLite"]
    W --> DB
    A --> S["Snapshot and artifact storage"]
    W --> S

Loading

For operators, the repository includes Docker, Alembic migrations, API-key management, a Redis worker mode, and a local SQLite mode for lightweight evaluation. Detailed operational commands live in the source tree and project documentation instead of this public overview.

Organization provisioning is explicit and keeps keys server-side:

python -m atlas.interfaces.cli create-org --name "Investment Team" --slug investment-team
python -m atlas.interfaces.cli create-key --org-id org_... --name production --scopes read,run

API Surface

Area	Endpoints
Portfolios	POST /portfolios, GET /portfolios, GET /portfolios/{id}, PUT /portfolios/{id}
Analyses	POST /analyses, GET /analyses, GET /analyses/{id}
Reports	POST /analyses/{id}/report, GET /analyses/{id}/report, GET /reports
Agent	POST /agent/ask, GET /agent/traces/{id}
Artifacts	GET /artifacts/{run_id}/{name}
System	GET /health

Repository Guide

src/atlas/
  platform/      Contracts, snapshots, database, queue, runtime
  domain/        Data ingestion, engines, validation, reports
  agent/         Planning, narration, citations, evals, traces
  interfaces/    FastAPI app, worker, CLI, React bundle hosting
frontend/        React/Vite interface and deployment proxy
migrations/      Alembic database migrations
docs/            Decisions, validation, limitations, figures
tests/           Contracts, API, engines, reports, agent, citations
scripts/         Validation reports and full-stack Compose smoke test

Roadmap

Track	Status
Deterministic engine foundation	Complete
FastAPI, persistence, auth, queue	Complete
ALFRED point-in-time ingestion and hybrid model validation	Implemented; keyed rerun pending
Governed agent with cited narratives	Complete
Macro monitor	Complete
Public proof and hosted user experience	In progress

Limitations

AtlasOS is intentionally transparent about what it does not yet claim. Current limitations include monthly crisis-detection granularity, on-demand alerts rather than automatic delivery, market-multiple valuation rather than a full DCF stack, aggregate fallbacks when company histories are unavailable and no billing layer. See docs/limitations.md for the full record.

License

No open-source license has been published for this repository yet. Until a LICENSE file is added, all rights are reserved by the repository owner. Before using AtlasOS outside evaluation or review, confirm the intended commercial or open-source license.

Disclaimer

AtlasOS is analytical software. It does not provide investment, accounting, legal, tax, or risk-management advice. Outputs should be reviewed by qualified professionals before they are used in investment, valuation, reporting, or committee decisions.