Atlantis Core Framework - Atlantis Core Docs

Atlantis Core is the reusable decision framework below options, perps, spot, scanners, dashboards, live trading, paper trading, replay, and research.

It turns adapter-normalized market state into evidence-rich trade theses, permission decisions, lifecycle objects, and outcome records. The framework deliberately avoids broker payloads, venue schemas, database rows, option strike lookup, and dashboard response models.

Atlantis Core architecture map

Current implementation status The first framework spine is implemented and verified: time/events, market snapshots, features, patterns, scoring, signal intents, permission, lifecycle, expression boundaries, mark/close observations, outcome records, legacy outcome parity, and adapter boundary tests.

What We Built

The current repository implements the first instrument-agnostic vertical slice:

ReferenceTime
  -> EventEnvelope[]
  -> MarketSnapshot
  -> FeatureVector
  -> PatternHit[]
  -> TradeHypothesis
  -> SignalIntent
  -> PermissionDecision
  -> PositionIntent
  -> ExposureExpression
  -> OpenExposure
  -> MarkRecord / LifecycleTransition
  -> OutcomeRecord

The point is not to copy legacy Atlantis module-for-module. The point is to preserve its durable behavior while removing historical coupling to options, specific venues, process wiring, and TimescaleDB tables.

What Core Owns

Area	Core object examples	Purpose
Time discipline	`ReferenceTime`, `Clock`, `CycleContext`	Make live, replay, and research use the same as-of semantics
Event ingestion boundary	`EventEnvelope`, `EventLineage`, `AdapterEventBatch`	Normalize adapter output without leaking raw venue payloads
Market state	`MarketSnapshot`, `PriceCapability`, `VolumeCapability`	Represent capability-bearing state with explicit availability
Feature extraction	`FeatureDefinition`, `FeatureRegistry`, `FeatureVector`	Compute deterministic features from bounded snapshots
Pattern detection	`PatternDefinition`, `PatternHit`, `PatternRegistry`	Emit evidence, availability, version, and definition hash
Scoring	`TradeHypothesis`, `EvidenceStack`, `ConvictionBreakdown`	Aggregate pattern evidence into directional hypotheses
Signal intent	`SignalIntent`, `ExposurePreference`, `IntentConstraints`	Express the thesis without selecting an instrument contract
Permission	`PermissionDecision`, `RiskContext`, `ReasonCode`	Admit, reject, defer, or downgrade the intent with reason codes
Lifecycle	`PositionIntent`, `OpenExposure`, `LifecycleTransition`	Track state changes without broker orders
Outcomes	`MarkRecord`, `CloseEvent`, `OutcomeRecord`	Preserve path labels and economic labels separately

What Core Does Not Own

Core does not own raw Delta, Zerodha, OpenAlgo, FastAPI, TimescaleDB, React, or broker order payloads.

Those belong in adapters or runtime layers:

Venue adapters normalize market payloads into EventEnvelope.
Instrument adapters express a SignalIntent as spot, perp, future, option, or no viable expression.
Execution adapters place or simulate orders.
Persistence adapters serialize core objects.
UI adapters present views without reshaping the domain.

Why This Matters

Legacy Atlantis contains valuable behavior, but it was often embedded inside options-specific or runtime-specific code. The rewrite keeps the valuable parts and makes them portable:

no hidden latest-row reads
no wall-clock reads inside core logic
missing, stale, invalid, and withheld data remain distinct
signal generation is gate-free, while permission is reason-coded
lifecycle states are append-only and replayable
path outcomes and economic outcomes are separate labels
tests encode behavior before migration changes land

Current Verification Standard

The current framework checkpoint is verified by:

python -m pytest
ruff check .
ruff format --check .

The suite includes contract tests, replay-safety tests, feature/window tests, pattern availability tests, scoring tests, signal intent tests, permission tests, lifecycle tests, adapter boundary tests, and the first legacy parity fixture.

Reading Order

Quickstart for the smallest working mental model.
Time and events for replay safety.
Market state for capability blocks and snapshots.
Features and patterns for deterministic evidence.
Scoring to permission for thesis and risk flow.
Lifecycle and outcomes for state and labels.
Adapters for where raw venue behavior enters and exits.
Legacy parity for preserving old Atlantis lessons.
Contract reference for a compact object map.