railtracks AGENTS.md

Repository Overview

Railtracks (rt) is a Python framework for building agentic systems: agents, tools, and multi-step flows defined entirely in standard Python (no YAML/DSLs). This is a uv workspace monorepo:

Root
├── packages/railtracks/          # The actual "railtracks" PyPI package
│   ├── pyproject.toml            # Package dependencies (add new deps here, in optional-dependencies for extras)
│   ├── src/railtracks/           # Source (module is railtracks, package dir uses underscore)
│   └── tests/                    # unit_tests/, integration_tests/, end_to_end/, llm_live_tests/
├── pyproject.toml                # Root workspace: dev-tooling deps only (docs/test/lint groups), NOT package deps
├── docs/                         # mkdocs documentation source
├── examples/                     # Example scripts
└── scripts/                      # CI helper scripts (dependency sorting, license checks, docs validation)

Accessing docs

Full documentation lives at https://docs.railtracks.org/ (works even if this file is read standalone, without the repo). Locally, the source is under docs/documentation/ and docs/observability/; preview with mkdocs serve (see Common Commands below). Doc URLs mirror the source path, e.g. docs/documentation/invocation/flows.md -> https://docs.railtracks.org/documentation/invocation/flows/.

Setup

uv sync --group dev
uv pip install -e "packages/railtracks[all]"   # or a specific extra, e.g. [visual], [retrieval]

Common Commands

# Lint / format (must pass before commit, CI enforces this)
ruff check --fix
ruff format

# Unit tests only (fast, ~10s)
pytest packages/railtracks/tests/unit_tests/ -v --timeout=30

# Unit + integration tests (excludes llm_live_tests and end_to_end/retrieval, per root pyproject.toml addopts)
pytest -s -v packages/railtracks/tests/unit_tests/ packages/railtracks/tests/integration_tests/

# Single test file / test
pytest packages/railtracks/tests/unit_tests/nodes/test_x.py -v
pytest packages/railtracks/tests/unit_tests/nodes/test_x.py::test_name -v

# Dependency sort check (CI enforced)
python scripts/check_dependencies_sorted.py

# Docs
mkdocs serve            # local preview at localhost:8000
mkdocs build --strict --verbose