mkdocs.yml

site_name: Railtracks Docs
site_url: https://docs.railtracks.org/
site_description: "Railtracks is a Python framework for building agents and harnesses: the loop, tools, context, and controls around an LLM."

hooks:
  - scripts/mkdocs_hooks.py

watch:
  - packages/railtracks/src/railtracks

repo_name: railtracks
repo_url: https://github.com/RailtownAI/railtracks/

theme:
  name: material
  logo: assets/logo.svg
  favicon: assets/logo.svg

  custom_dir: docs/overrides

  palette:
    - scheme: slate
      primary: black
      toggle:
        icon: material/brightness-5
        name: Switch to light mode

    - scheme: default
      primary: white
      toggle:
        icon: material/brightness-4
        name: Switch to dark mode

  features:
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.sections
    - navigation.indexes
    - navigation.prefetch
    - navigation.path
    - navigation.top
    - navigation.footer
    - search.suggest
    - content.code.copy
    - content.code.highlight
    - content.code.annotate
    - content.tooltips

plugins:
  - search
  - llmstxt:
      markdown_description: Each link below is a clean Markdown copy of one docs page. llms-full.txt holds every page in a single file.
      full_output: llms-full.txt
      sections:
        Home:
          - index.md
        Agent Development:
          - documentation/*.md
        Retrieval:
          - retrieval/*.md
        Evaluations:
          - evaluations/*.md
        Observability:
          - observability/*.md
        Integrations:
          - integrations/*.md
        Tutorials:
          - tutorials/*.md

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - admonition
  - pymdownx.details
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:mermaid2.fence_mermaid_custom
  - abbr
  - pymdownx.inlinehilite
  # Glossary terms are appended to every page so `abbr` can turn them into
  # hover definitions. The appended file is generated from docs/glossary.md
  # by scripts/mkdocs_hooks.py.
  - pymdownx.snippets:
      auto_append:
        - docs/includes/glossary_tooltips.md
  - pymdownx.highlight:
      anchor_linenums: true
      pygments_lang_class: true
      line_spans: __span

extra_css:
  - css/extra.css

extra:
  generator: false

# Generated include, appended to every page rather than published as one.
exclude_docs: |
  includes/

# Per-middleware prebuilt pages are intentionally kept out of the sidebar (they are
# reached from the prebuilt Overview catalog) so the nav stays clean as the
# catalog grows. Listing them here silences the "not in nav" build warning.
not_in_nav: |
  /documentation/agent_design/middleware/prebuilt/list/*.md

validation:
  links:
    anchors: warn

nav:
  - Home: index.md

  - Agent Development:
      - Getting Started:
          - Quickstart: documentation/getting_started/quickstart.md
          - Installation: documentation/getting_started/installation.md
          - LLM Setup: documentation/getting_started/llm_setup.md
          - Contributing to the Docs: documentation/getting_started/contributing_docs.md
          - Upgrading to 1.5.0: documentation/upgrading/1_5_0.md
      - Harness:
          - Agent Harness: documentation/harness/overview.md
      - Agent Design:
          - Overview: documentation/agent_design/overview.md
          - Tools:
              - Prebuilt Tools:
                  - Overview: documentation/agent_design/tools/prebuilt/overview.md
                  - To Do Tool: documentation/agent_design/tools/prebuilt/todos.md
                  - Key-Value Memory Tool: documentation/agent_design/tools/prebuilt/key_value_memory.md
                  - Web Search Tool: documentation/agent_design/tools/prebuilt/websearch.md
              - Function Tools: documentation/agent_design/tools/function_tools.md
              - Agents as Tools: documentation/agent_design/tools/agents_as_tools.md
              - MCP: documentation/agent_design/tools/mcp.md
          - LLMs:
              - System Messages: documentation/agent_design/llms/system_messages.md
              - Modalities: documentation/agent_design/llms/modalities.md
              - Failures: documentation/agent_design/llms/handling_failures.md
              - Common Hyperparameters: documentation/agent_design/llms/common_hyperparams.md
              - Structured Output: documentation/agent_design/structured_extraction.md
          - Decision Nodes: documentation/agent_design/decision_nodes.md
          - Middleware:
              - Overview: documentation/agent_design/middleware/overview.md
              - Custom: documentation/agent_design/middleware/custom.md
              - Guardrails:
                - Overview: documentation/agent_design/middleware/guardrails/overview.md
                - Quickstart: documentation/agent_design/middleware/guardrails/quickstart.md
                - Contributing: documentation/agent_design/middleware/guardrails/contributions.md
              - Verifiers: documentation/agent_design/middleware/verifiers/overview.md
              - Prebuilt:
                - Overview: documentation/agent_design/middleware/prebuilt/overview.md
                - Contributing: documentation/agent_design/middleware/prebuilt/contributions.md
              

      - Agent Invocation:
          - Direct Invocation: documentation/invocation/call.md
          - Flow Invocation: documentation/invocation/flows.md
          - Message History: documentation/invocation/message_history.md
      - Advanced:
          - Context: documentation/advanced/context.md

  - AI Coding:
      - Claude Code Plugin: documentation/getting_started/claude_code_plugin.md
      - AI Coding Assistants: documentation/getting_started/ai_setup.md

  - Retrieval:
    - Retrieval Runtime:
      - Quickstart: retrieval/runtime/quickstart.md
      - Ingestion: retrieval/runtime/ingestion.md
      - Retrieval: retrieval/runtime/retrieval.md
      - Module Packages: retrieval/runtime/module_packages.md
    - Components:
      - Design: retrieval/components/design.md
      - Loading:
          - Base Class: retrieval/components/ingestion/base.md
          - Built-in Loaders: retrieval/components/ingestion/methods.md
      - Chunking:
          - Base Class: retrieval/components/chunking/base.md
          - Built-in Methods: retrieval/components/chunking/methods.md
      - Embeddings:
        - Overview: retrieval/components/embeddings/overview.md
        - Built-in Methods: retrieval/components/embeddings/methods.md
      - Stores:
          - Base Class: retrieval/components/stores/base.md
          - Backends: retrieval/components/stores/backends.md

  - Evaluations:
      - Preface: evaluations/preface.md
      - Quickstart: evaluations/quickstart.md
      - Visualization: evaluations/visualization.md
      - Conductr:
          - Evaluating Agent Runs: evaluations/conductr.md
          - Hosted Evaluations: evaluations/conductr_hosted.md
      - Metrics:
          - Metrics Overview: evaluations/metrics/metrics.md
          - Categorical Metrics: evaluations/metrics/categorical.md
          - Numerical Metrics: evaluations/metrics/numerical.md
      - Evaluators:
          - Evaluator Abstraction: evaluations/evaluators/evaluators.md
          - ToolUseEvaluator: evaluations/evaluators/tool_use_evaluator.md
          - LLMInferenceEvaluator: evaluations/evaluators/llm_inference_evaluator.md
          - JudgeEvaluator: evaluations/evaluators/judge_evaluator.md

  - Observability:
      - AgentHub:
          - Local:
            - Current Visualizer: observability/agenthub/local_v2.md
            - Legacy Visualizer: observability/agenthub/local.md
          - Cloud: observability/agenthub/cloud.md
      - Tracking:
          - Logging: observability/tracking/logging.md
          - Broadcasting: observability/tracking/broadcasting.md
          - Error Handling: observability/tracking/error_handling.md

  - Integrations:
    - Overview: integrations/overview.md
    - Language Models:
        - Providers: integrations/llms/providers.md
        - Platforms: integrations/llms/platforms.md
        - Streaming: integrations/llms/streaming.md
    - MCP:
        - Github: integrations/mcps/github.md
        - Slack: integrations/mcps/slack.md
        - Email: integrations/mcps/notion.md
    - Storage & Databases:
        - Overview: integrations/storage/overview.md
        - AWS S3: integrations/storage/s3.md
        - Azure Blob Storage: integrations/storage/azure_blob.md
        - Google Cloud Storage: integrations/storage/gcs.md
        - SQL Databases: integrations/storage/sql.md
    - Other:
        - Python Sandbox: integrations/other/python_sandbox.md
        - Shell: integrations/other/shell_bash.md
        - Websearch: integrations/other/websearch_integration.md

  - Tutorials:
      - Walkthroughs:
          - Guides:
              - Building your first agent: tutorials/walkthroughs/byfa.md
              - Running your first agent: tutorials/walkthroughs/ryfa.md
              - Agents as Tools: tutorials/walkthroughs/agents_as_tools.md
              - Prompts and Context: tutorials/walkthroughs/prompts_and_context.md
              - Flows: tutorials/walkthroughs/flows.md
              - FastAPI Integration: tutorials/walkthroughs/fastapi.md
              - "Human-in-the-Loop: LLM Reviewers": tutorials/walkthroughs/hil_llm_reviewer.md
              - "Human-in-the-Loop: Webhook Approvals": tutorials/walkthroughs/hil_webhook_approval.md
          - Videos:
              - Multiagent Systems: tutorials/videos/multiagent.md
              - Multimodal Agent: tutorials/videos/multimodal_agent.md
              - AgentHub: tutorials/videos/agenthub.md
              - Evaluation: tutorials/videos/evaluation.md
      - Notebooks:
          - Agent Architectures: tutorials/notebooks/architectures.md
          - FastAPI Integration: tutorials/notebooks/fastapi.md
          - File Embedding: tutorials/notebooks/file_embedding.md
          - Retrieval Benchmark: tutorials/notebooks/retrieval-benchmark.md
      - Concepts:
          - Core:
              - Agents: tutorials/concepts/agents.md
              - Tools: tutorials/concepts/tools.md
              - MCP: tutorials/concepts/mcp.md
              - Prompts and Context: tutorials/concepts/prompts_and_context.md
              - RAG: tutorials/concepts/RAG.md
              - Async/Await: tutorials/concepts/async_await.md
              - Vector Stores: tutorials/concepts/vector_store.md
          - Architectures:
              - Overview: tutorials/concepts/architectures/overview.md
              - Validation Loops: tutorials/concepts/architectures/validation_loop.md
              - Sequential Flows: tutorials/concepts/architectures/sequential.md

  - Glossary: glossary.md

  - API Reference: api_reference.md