railtracks copilot-instructions.md

Railtracks Development Instructions

Always reference these instructions first and fall back to search or bash commands only when you encounter unexpected information that does not match the info here.

Repository Overview

Railtracks is a Python framework for building agentic systems. The repository is a uv workspace containing a single published package:

• packages/railtracks/ — the SDK. Everything public is re-exported at the package root and used as import railtracks as rt.

The root pyproject.toml holds workspace config and dev tooling only (docs, test, lint dependency groups). Package dependencies — including every optional extra — live in packages/railtracks/pyproject.toml.

Working Effectively

Prerequisites

• Python 3.10+ (requires-python = ">=3.10"). CI runs 3.10.
• uv for dependency management.

Development Environment Setup

uv sync --group dev                              # docs + test + lint tooling
uv pip install -e "packages/railtracks[all]"     # SDK with all optional extras

The SDK is deliberately thin by default; features gate behind extras declared in packages/railtracks/pyproject.toml (visual, retrieval, chroma, portkey, stores-*, …).

retrieval is not part of [all]. Install it explicitly when working on the RAG stack:

uv pip install -e "packages/railtracks[all,retrieval]"

Build and Test Commands

Linting and formatting (runs in ~1 second)

ruff is configured in the root pyproject.toml: line-length 88, target py310.

# What CI checks
ruff check . --no-fix
ruff format --check .

# What you run locally to fix it
ruff check --fix
ruff format

Testing (pytest, asyncio_mode = "auto")

Live LLM tests (tests/llm_live_tests) and retrieval end-to-end tests are excluded by addopts in the root pyproject.toml, so a bare pytest never needs an API key.

# The core suite, matching CI
pytest -s -v \
  --ignore=packages/railtracks/tests/unit_tests/retrieval \
  packages/railtracks/tests/unit_tests/ packages/railtracks/tests/integration_tests/

# Retrieval suite (needs the retrieval extra)
pytest -s -v packages/railtracks/tests/unit_tests/retrieval/

# A single test
pytest packages/railtracks/tests/unit_tests/path/to/test_file.py::test_name