research_os

Imported from Yooh-an/ThesisOS (src/research_os/AGENTS.md). Install upstream with npx skills add Yooh-an/ThesisOS --skill research_os. Copyright stays with the author.

src/research_os/AGENTS.md - Deterministic Engine Rules

Scope: all files under src/research_os/.

Purpose

This package is the source of truth for ThesisOS deterministic data transformations, calculations, readiness checks, research packets, and reports.

Rules

1. No LLM calls in deterministic analysis modules.
2. No frontend imports.
3. No FastAPI imports unless the module is explicitly an adapter boundary.
4. Use repository/service boundaries for DB access; do not scatter direct DuckDB access through calculation modules.
5. Keep raw, standardized, feature, and research data separate.
6. Preserve entity, period, source, statement, and calculation metadata.
7. Never silently fill missing numeric values with zero.
8. Missing numeric values remain None/null; calculations return None/NaN plus warnings when inputs are unavailable or invalid.
9. Use explicit formulas in docstrings.
10. Add pytest tests for every calculation function.
11. Use local fixtures, mocks, or temp DBs for tests.
12. No live network calls in tests.
13. No external calls except explicit connector modules or explicitly requested connector tasks.
14. No frontend logic, display formatting, or browser credential handling.

Module Boundaries

• data_sources: explicit fetch/cache clients for external data; network disabled unless configured by a connector task
• ingestion: raw/local ingestion workflows
• storage: database connections, schema, migrations, and repositories
• entities: entity and corp-code metadata
• financials: account mapping, standardization, ratios, TTM, features, quality reports
• market: manual/local prices and market readiness
• peer: peer comparison and scoring
• macro: local macro catalog, CSV ingestion, observations, features, readiness; future live connectors must stay explicit
• valuation: valuation multiples, target inputs, target policy, deterministic target prices, internal ratings, valuation views, and target revisions
• events: event detection and classification
• thesis: thesis objects, evidence links, and updates
• claims: claim objects, evidence links, update logs, and deterministic evidence reviews
• llm: optional draft-only review provider abstraction and Codex adapter
• reporting: research packets and deterministic Markdown reports
• pipeline: local orchestration and quality/readiness checks

Future news and scenario modules should follow the same separation:

• source catalog / explicit local ingestion
• raw metadata
• deterministic feature/event/scenario output
• evidence links
• packet/report integration

Target Price/Internal Rating Boundary

Target price and internal rating calculations are allowed only in valuation target modules and must use explicit local inputs and policy.

Allowed values:

• internal research rating: buy, hold, sell, not_rated
• valuation view: positive, neutral, negative, not_available
• target revision: raise, maintain, cut, not_available

These are internal research outputs, not trading instructions, order instructions, position sizing, claim statuses, or thesis statuses.

LLM/Codex Boundary

LLM/Codex modules are optional review adapters only. They must not:

• mutate source data
• update thesis or claim status/confidence
• create evidence links automatically
• calculate target prices
• generate internal ratings
• generate trading/order/position-sizing instructions
• read Codex credentials or inspect ~/.codex

Codex integration must use official Codex CLI/SDK invocation paths only and must require explicit enablement.

Calculation Output Requirement

Calculation functions should return structured data with:

• value columns
• warning columns or quality/readiness report
• period metadata
• entity/source metadata where applicable
• calculation version where applicable