Skip to content

AGENTS.md

Latest commit

 

History

History
82 lines (62 loc) · 3.46 KB

AGENTS.md

File metadata and controls

82 lines (62 loc) · 3.46 KB
Raw

QuantMind — Agent Instructions

Guidance for coding agents contributing to this repository. Keep this file aligned with CLAUDE.md (same core rules); update both in the same change.

What This Is

QuantMind is a knowledge extraction and retrieval library for quantitative finance, built on top of the OpenAI Agents SDK. It is a domain library, not an agent framework: runtime, tracing, tool scaffolding, and multi-agent handoff all come from openai-agents.

Module Map

Module Role
quantmind/knowledge/ Pydantic data standard (FlattenKnowledge / TreeKnowledge / GraphKnowledge) — dependency leaf
quantmind/configs/ Flow cfg + typed inputs (BaseFlowCfg, discriminated unions) — depends only on knowledge
quantmind/preprocess/ Deterministic fetch / format / clean / time utilities — depends only on utils
quantmind/flows/ Apex layer: end-to-end pipeline functions (paper_flow, batch_run)
quantmind/magic.py resolve_magic_input: natural language → (input, cfg)
quantmind/mind/ Cognitive layer (memory protocol); landing via the Agents SDK migration (#71)
quantmind/utils/ Logger only — keep it that way

The pre-migration agent runtime was removed and archived on the archive/agent-runtime-final branch. Reference it for history; never resurrect it into master.

Setup and Verification

uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
bash scripts/verify.sh   # canonical "is this branch shippable" check

scripts/verify.sh runs five fast-fail steps (ruff format --check, ruff check, basedpyright, lint-imports, pytest --cov). CI runs the exact same script, so a green local run means a green PR. Do not bypass pre-commit / pre-push hooks unless the user explicitly authorizes it — fix the underlying issue instead.

Architecture Constraints (stable)

  1. Library, not framework — functions over classes, Protocol over ABC, no plugin registries, no hook discovery, no CLI.
  2. Do not rebuild the agent runtime — use openai-agents directly; no QuantMind-side facades over from agents import ....
  3. Pydantic at boundaries, frozen dataclass internally — Pydantic (frozen=True, extra="forbid") for anything exposed to an LLM or a user; frozen dataclasses for internal value types.
  4. Import boundaries are contracts — import-linter (configured in pyproject.toml) pins the dependency graph; never work around a failing contract.
  5. Absolute imports across module boundaries.
  6. No meaningless wrappers — a method must add logic, abstraction, or a side effect beyond the call it wraps; otherwise inline it.

Tests and Examples

A new feature ships with a unit test and a focused example:

  • Tests: tests/<module>/, subclass unittest.TestCase, mock external services, cover success and failure paths.
  • Examples: examples/<module>/, one simple usage per file.

Communication

  • Commit messages: English, Conventional Commits.
  • PR titles, PR bodies, and issue bodies: English.
  • Code comments and docstrings: English, Google style.

Development Workflows

For commit, pull-request, or component-implementation tasks, load the quantmind-dev skill and follow the matching reference:

  • .agents/skills/quantmind-dev/SKILL.md (this toolchain)
  • .claude/skills/quantmind-dev/SKILL.md (Claude Code)

The two copies are identical; when changing the skill, update both in the same change.