local-development.md

Local Development

Environment

Use the pyvalue conda environment for project work.

Example install:

python -m pip install -e .[dev]
conda activate pyvalue

Project Layout

Main repo areas:

• src/pyvalue/: application code
• tests/: pytest suite
• screeners/: YAML screen definitions
• data/: local database, logs, and output artifacts
• private/: local credentials and config
• docs/: project documentation
• skills/: repo-local Codex skills and helper assets

Main application subsystems in src/pyvalue/:

• universe/
• ingestion/
• normalization/
• marketdata/
• metrics/
• money/ and screening/
• persistence/ (storage/, migrations.py, database_review_docs.py)
• cli/

Common Development Workflows

Run tests:

conda run -n pyvalue pytest

Run formatting and checks:

conda run -n pyvalue ruff format .
conda run -n pyvalue ruff check .
conda run -n pyvalue mypy src/ tests/

Adding New Metrics

Typical workflow:

1. confirm normalized inputs exist
2. add or extend normalization only if needed
3. implement the metric in src/pyvalue/metrics/
4. register it in src/pyvalue/metrics/__init__.py
5. add or update tests
6. update docs/reference/metrics.md

Documentation Expectations

When behavior changes:

• update the relevant docs page under docs/
• avoid keeping the same explanation in multiple files
• keep the root README short and link to the canonical topic page