railtracks: Instructions file for Codex

Repository Overview

Railtracks (rt) is a Python framework for building agent harnesses: the loop, tools, context, controls, and record around a model, 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
├── plugins/railtracks/           # Claude Code plugin (listed in .claude-plugin/marketplace.json); skills/ is generated
└── scripts/                      # CI helper scripts (dependency sorting, license checks, docs validation, plugin sync)

Accessing docs

Full documentation is at https://docs.railtracks.org/ and is reachable without a checkout of this repo. The source is under docs/, with navigation in mkdocs.yml. Doc URLs mirror the source path, e.g. docs/documentation/invocation/flows.md -> https://docs.railtracks.org/documentation/invocation/flows/. To verify a docs change, run mkdocs build --strict, which fails on broken links and nav entries.

Setup

Python 3.11+ (requires-python = ">=3.11", CI runs 3.11) and uv.

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

[all] pulls in the whole RAG stack (connectors, OCR, vector-store backends). For the retrieval pipeline without that weight, [retrieval-core] is the lighter opt-in (chunking, embedding, in-memory store, local loaders).