alpha-engine-lib

Part of Nous Ergon — Autonomous Multi-Agent Trading System. Repo and S3 names use the underlying project name alpha-engine.

Shared utility library used by all 6 modules of Nous Ergon. Cross-cutting concerns only — logging, freshness checks, trading-calendar arithmetic, ArcticDB helpers, agent-decision capture, LLM cost tracking. No proprietary trading logic, no model weights, no agent prompts.

The lib's job is to keep the same code from being maintained six times.

---

Install

# requirements.txt
alpha-engine-lib @ git+https://github.com/cipher813/alpha-engine-lib@v0.4.0

Tagged releases: v0.1.0, v0.2.0, v0.3.0, v0.4.0, etc. Consumers pin to a specific tag. Breaking changes bump the minor version while Alpha Engine is in pre-1.0.

# With optional extras
pip install "alpha-engine-lib[arcticdb] @ git+https://github.com/cipher813/alpha-engine-lib@v0.4.0"

Extra	Pulls in	When you need it
[arcticdb]	arcticdb, pandas	Anything that calls check_arcticdb_fresh or the ArcticDB read/write helpers
[flow_doctor]	flow-doctor	Logging integration that escalates ERROR-level events to flow-doctor
[rag]	psycopg2-binary, pgvector, numpy	The rag submodule — Neon pgvector RAG retrieval/ingestion
[dev]	pytest, lint tooling	Local development

Modules

logging — structured logging + flow-doctor attach

Replaces the near-identical log_config.py copies that used to live in alpha-engine-data and alpha-engine-executor. Consumers call setup_logging once at process startup:

from alpha_engine_lib.logging import setup_logging

setup_logging("data-collector", flow_doctor_yaml="/path/to/flow-doctor.yaml")

• Text mode by default; JSON via ALPHA_ENGINE_JSON_LOGS=1
• Flow-doctor attaches as an ERROR-level handler when FLOW_DOCTOR_ENABLED=1 (requires [flow_doctor] extra)

preflight — fail-fast connectivity + freshness checks

Runs at the top of every entrypoint, before any real work starts. Primitives live on BasePreflight; each consumer subclasses and overrides run():

from alpha_engine_lib.preflight import BasePreflight

class DataPreflight(BasePreflight):
    def __init__(self, bucket, mode):
        super().__init__(bucket)
        self.mode = mode

    def run(self):
        self.check_env_vars("AWS_REGION")
        if self.mode == "phase1":
            self.check_env_vars("FRED_API_KEY", "POLYGON_API_KEY")
        self.check_s3_bucket()
        if self.mode == "daily":
            self.check_arcticdb_fresh("universe", "SPY", max_stale_days=4)

Failed checks raise RuntimeError with an explanatory message. Consumers catch nothing — the raise propagates up through main() → non-zero exit → Step Function HandleFailure → flow-doctor notification. The point is to fail before paying for any LLM calls or downstream work.

arcticdb — read/write helpers + symbol enumeration

Wrappers around the ArcticDB Python client. Standardizes the URI format, library naming, and read paths so each consumer doesn't reinvent the connection logic.

dates — trading-day arithmetic

now_dual() returns a (calendar_date, trading_day) pair following the rule trading_day = last_closed_trading_day(now). Strictly backward-looking; never ahead. session_for_timestamp(ts) resolves any timestamp to its trading session. Used at every artifact-write site to prevent calendar/trading-day drift between modules.

trading_calendar — NYSE holiday detection

Pure-Python NYSE calendar through 2030. No pandas-market-calendars dependency.

decision_capture — agent decision audit logger

Captures every agent decision as a structured artifact: prompt metadata (id + version), input snapshot, agent output, and cost. Each decision becomes replayable, auditable, and attributable to a specific prompt revision. Backbone of the Phase 2 measurement substrate.

cost — LLM cost tracking

Token-aware cost computation following Anthropic's prompt-caching semantics (cache-write vs cache-read pricing). Used by every LLM call site to attach a cost_usd to its output.

agent_schemas — canonical LLM-output Pydantic schemas

Shared contract surface for the 14 LLM-output classes used in with_structured_output(...) calls across the research pipeline (sector quant + qual + peer review, macro economist + critic, held-stock thesis update, CIO, eval-judge rubric). Lives here so downstream tooling — replay harness in alpha-engine-backtester, future cheap-model-concordance signals — can validate against the canonical contract without a heavy cross-repo dep on research.

from alpha_engine_lib.agent_schemas import (
    QuantAnalystOutput,
    JointFinalizationOutput,
    CIORawOutput,
    HeldThesisUpdateLLMOutput,
    resolve_schema_for_agent,
)

# Dispatch by captured agent_id (e.g. "sector_quant:technology" → QuantAnalystOutput)
schema = resolve_schema_for_agent(agent_id)

SCHEMA_BY_AGENT_ID_BASE covers the 6 canonical agent families: sector_quant, sector_qual, sector_peer_review, macro_economist, ic_cio, thesis_update. Validators that defend observed LLM failure modes (sector-modifier clamp, JSON-string-as-list parser, min_length=1 on CIO decisions) move with their classes.

pillars — canonical 6-pillar attractiveness scoring shapes

Pydantic shapes for the institutional / SOTA refactor of research-module composite scoring — replaces the opaque quant_score + qual_score two-bucket model with a canonical 6-pillar decomposition: Quality / Value / Momentum / Growth / Stewardship / Defensiveness. Pillar set is the AQR Style Premia / Morningstar Economic Moat / Greenblatt / Piotroski / Fama-French / Asness "QMJ" consensus.

from alpha_engine_lib.pillars import (
    PILLARS,
    MoatAssessment,
    PillarSubscore,
    QualitativePillarAssessment,
)

# Qual Analyst emits via with_structured_output(QualitativePillarAssessment).
# Each of the 6 PillarSubscore fields carries 0-100 + confidence + evidence;
# the Quality pillar additionally carries a structured MoatAssessment
# (Morningstar wide/narrow/none + 6-archetype primary moat type + trend) —
# the qualitative core of Quality, persisted per ticker for time-series
# trend tracking.

Each PillarSubscore decomposes into optional quant_component (from the factor substrate) + qual_component (from the agent rubric) for traceability through the composite scoring layer. Catalyst is preserved as an orthogonal catalyst_horizon_modulation: int ∈ [-20, 20] (a horizon shift on near-term attractiveness), not a 7th pillar weight.

Origin: 2026-05-20 attractiveness-pillars-260520 plan-doc arc. Phase 1 (this module) ships the schema layer; Phases 2-7 wire it through alpha-engine-research, alpha-engine-data, alpha-engine-backtester, and alpha-engine-dashboard.

rag — semantic retrieval over SEC filings, transcripts, and theses

Neon pgvector backbone shared by alpha-engine-research (qual analyst's query_filings tool) and alpha-engine-data (weekly RAGIngestion step). Re-exports a small surface — retrieve, ingest_document, document_exists, embed_texts, get_connection, is_available — and ships the canonical schema.sql as package data.

from alpha_engine_lib.rag import retrieve

results = retrieve(
    query="competitive risks and market position",
    tickers=["AAPL"],
    doc_types=["10-K", "10-Q", "earnings_transcript"],
    top_k=8,
)

Requires the [rag] extra. Embeddings are Voyage voyage-3-lite (512d); the database backend is Neon Postgres with pgvector + HNSW indexes.

How it's used

All six Nous Ergon module repos depend on this lib:

Module	Repo	What it imports from here
Data	alpha-engine-data	logging, preflight, arcticdb, dates, trading_calendar, rag (ingestion)
Research	alpha-engine-research	logging, decision_capture, cost, dates, rag (retrieval), agent_schemas (canonical LLM-output contracts)
Predictor	alpha-engine-predictor	logging, preflight, arcticdb, dates
Executor	alpha-engine	logging, preflight, arcticdb, dates, trading_calendar
Backtester	alpha-engine-backtester	logging, preflight, arcticdb, dates, agent_schemas (replay-harness Pydantic validation)
Dashboard	alpha-engine-dashboard	logging, arcticdb, dates

Development

git clone https://github.com/cipher813/alpha-engine-lib.git
cd alpha-engine-lib
pip install -e ".[dev,arcticdb,flow_doctor]"
pytest

Scope discipline

This repo is intentionally narrow. Code lands here when at least two consumers would otherwise maintain their own copy. New modules land as their own minor release with per-consumer adoption — no lockstep updates.

Code that does not belong here:

• Anything tunable (scoring weights, risk thresholds, sizing parameters) → alpha-engine-config (private)
• Agent prompts → alpha-engine-config (private)
• Module-specific business logic → that module's repo

License

MIT — see LICENSE.