Imported from Yooh-an/ThesisOS (
src/research_os/AGENTS.md). Install upstream withnpx 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
- No LLM calls in deterministic analysis modules.
- No frontend imports.
- No FastAPI imports unless the module is explicitly an adapter boundary.
- Use repository/service boundaries for DB access; do not scatter direct DuckDB access through calculation modules.
- Keep raw, standardized, feature, and research data separate.
- Preserve entity, period, source, statement, and calculation metadata.
- Never silently fill missing numeric values with zero.
- Missing numeric values remain
None/null; calculations returnNone/NaN plus warnings when inputs are unavailable or invalid. - Use explicit formulas in docstrings.
- Add pytest tests for every calculation function.
- Use local fixtures, mocks, or temp DBs for tests.
- No live network calls in tests.
- No external calls except explicit connector modules or explicitly requested connector tasks.
- 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 taskingestion: raw/local ingestion workflowsstorage: database connections, schema, migrations, and repositoriesentities: entity and corp-code metadatafinancials: account mapping, standardization, ratios, TTM, features, quality reportsmarket: manual/local prices and market readinesspeer: peer comparison and scoringmacro: local macro catalog, CSV ingestion, observations, features, readiness; future live connectors must stay explicitvaluation: valuation multiples, target inputs, target policy, deterministic target prices, internal ratings, valuation views, and target revisionsevents: event detection and classificationthesis: thesis objects, evidence links, and updatesclaims: claim objects, evidence links, update logs, and deterministic evidence reviewsllm: optional draft-only review provider abstraction and Codex adapterreporting: research packets and deterministic Markdown reportspipeline: 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
