mkdocs.yml

site_name: locus
site_description: 'Oracle Generative AI Agentic Harness. Locus is a Python agent harness: one Agent class, eight ways to combine agents, Oracle Cloud underneath, an admission gate in front of every consequential action, open to every provider.'
site_url: https://locusagents.ai/
repo_url: https://github.com/oracle/locus
repo_name: oracle/locus
edit_uri: edit/main/docs/

docs_dir: docs
strict: true

exclude_docs: |
  internal/
  doc-gen/
  diagrams/README.md
  diagrams/cards/README.md
  # Engineering notes that live next to the code they describe (linked from
  # the README and CHANGELOG on GitHub), not pages of the site.
  observation-pack.md

theme:
  name: material
  custom_dir: overrides
  logo: img/mark.svg
  favicon: img/mark.svg
  font:
    text: Inter
    code: JetBrains Mono
  palette:
  # First visit follows the operating system (the first entry has no scheme,
  # so Material resolves it from prefers-color-scheme); the toggle then cycles
  # system → light → dark and the choice is remembered per browser.
  - media: (prefers-color-scheme)
    toggle:
      icon: material/brightness-auto
      name: Switch to light mode
  - media: '(prefers-color-scheme: light)'
    scheme: default
    primary: custom
    accent: custom
    toggle:
      icon: material/brightness-7
      name: Switch to dark mode
  - media: '(prefers-color-scheme: dark)'
    scheme: slate
    primary: custom
    accent: custom
    toggle:
      icon: material/brightness-4
      name: Switch to system preference
  features:
  - navigation.instant
  - navigation.sections
  - navigation.tabs
  - navigation.tabs.sticky
  - navigation.indexes
  - navigation.top
  - navigation.footer
  - toc.follow
  - content.action.edit
  - content.action.view
  - content.code.copy
  - content.code.annotate
  - content.tabs.link
  - search.highlight
  - search.share
  - search.suggest

hooks:
- hooks/cache_bust.py
- hooks/build_metadata.py
- hooks/search_exclude.py
- hooks/inline_code_breaks.py
# After build_metadata so the Markdown twins carry the expanded build facts.
- hooks/llms_txt.py

extra_css:
- stylesheets/locus.css

extra_javascript:
- javascripts/header-home.js
- javascripts/copy-page.js
- javascripts/diagram-zoom.js
- javascripts/mobile-tables.js
- javascripts/output-blocks.js
- javascripts/table-filter.js
- javascripts/notebook-filter.js
- javascripts/sidebar-filter.js

copyright: <span class="footer-brand"><span class="footer-brand__o" aria-hidden="true"></span><span class="footer-brand__text">Oracle Generative AI</span></span><br><span class="footer-copy">Copyright &copy; 2025–2026 <span class="oracle-mark" aria-label="Oracle"></span> and/or its affiliates &middot; <a href="/legal/">Legal</a></span>

extra:
  homepage: https://locusagents.ai/
  # The model every generic example uses; the build hook expands
  # {{ locus_example_model }} everywhere, so change it here, not on the pages.
  example_model: oci:openai.gpt-5.5
  # Provider tab sets ({{ locus_model_tabs }}): one example model id per
  # provider, shown as linked tabs so a reader picks a provider once.
  model_tabs:
  - label: OCI
    model: oci:openai.gpt-5.5
  - label: OpenAI
    model: openai:gpt-4o
  - label: Anthropic
    model: anthropic:claude-sonnet-5-5
  - label: Self-hosted
    model: ollama:qwen3
  social:
  - icon: fontawesome/brands/github
    link: https://github.com/oracle/locus
    name: locus on GitHub
  - icon: fontawesome/brands/python
    link: https://pypi.org/project/locus-sdk/
    name: locus-sdk on PyPI
  generator: false

markdown_extensions:
- admonition
- attr_list
- md_in_html
- def_list
- footnotes
- pymdownx.details
- pymdownx.highlight:
    anchor_linenums: true
    line_spans: __span
    pygments_lang_class: true
- pymdownx.inlinehilite
# Notebook pages embed the notebooks source from the SDK repo: `.sdk` is
# where the deploy workflow checks it out, `../locus-sdk` the local
# convention (see README). check_paths makes a missing include fail the
# build instead of rendering an empty section.
- pymdownx.snippets:
    base_path: [., packages/locus-sdk-security]
    check_paths: true
# Mermaid diagrams render client-side via Material's built-in integration;
# the custom_fence is what routes ```mermaid to it instead of highlighting
# it as source. Required by docs/research/ and the concept diagrams.
- pymdownx.superfences:
    custom_fences:
    - name: mermaid
      class: mermaid
      format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed:
    alternate_style: true
- pymdownx.emoji:
    emoji_index: !!python/name:material.extensions.emoji.twemoji
    emoji_generator: !!python/name:material.extensions.emoji.to_svg
- tables
- toc:
    permalink: true

plugins:
- search
# The privacy plugin self-hosts every external asset. The header's version
# pill is rendered by hooks/build_metadata.py from the SDK this build was made
# with (config.extra.sdk_version), so nothing in the header is fetched live.
- privacy
- mkdocstrings:
    default_handler: python
    handlers:
      python:
        options:
          docstring_style: google
          show_source: true
          show_root_heading: true
          show_root_full_path: false
          separate_signature: true
          show_signature_annotations: true
          merge_init_into_class: true
          show_if_no_docstring: false
          inherited_members: true
          members_order: source

nav:
# Home (index.md) is reached via the header wordmark + logo (both link to "/"),
# so we don't repeat it as a tab here.
- Concepts:
  - Start here:
    - Multi-agent shapes: concepts/multi-agent.md
    - The Agent: concepts/agent.md
    - Agent loop: concepts/agent-loop.md
    - Tools: concepts/tools.md
    - Model providers: concepts/models.md
    - Capabilities: capabilities.md
  - Multi-agent shapes:
    - Overview and the eight protocols: concepts/multi-agent.md
    - Composition (pipelines): concepts/multi-agent/composition.md
    - StateGraph: concepts/multi-agent/graph.md
    - Functional API: concepts/multi-agent/functional.md
    - Graph streaming: concepts/graph-streaming.md
    - Orchestrator: concepts/multi-agent/orchestrator.md
    - Swarm: concepts/multi-agent/swarm.md
    - Handoff: concepts/multi-agent/handoff.md
    - A2A protocol: concepts/multi-agent/a2a.md
    - DeepAgent: concepts/deepagent.md
    - Production-readiness: concepts/multi-agent/production.md
  - Oracle Database 26ai: concepts/oracle-26ai.md
  - Agents:
    - State: concepts/state.md
    - Prompts: concepts/prompts.md
    - Conversation management: concepts/conversation-management.md
    - Structured output: concepts/structured-output.md
    - Termination: concepts/termination.md
    - Interrupts: concepts/interrupts.md
    - Hooks: concepts/hooks.md
    - Retry strategies: concepts/retry.md
    - Errors: concepts/errors.md
  - Tools:
    - Idempotency: concepts/idempotency.md
    - Executors: concepts/executors.md
    - MCP: concepts/mcp.md
    - Multi-modal providers: concepts/multi-modal-providers.md
  - The coding harness:
    - Overview: harness.md
    - OCI GenAI Sandboxes: harness/oci-sandbox.md
    - NVIDIA OpenShell: harness/openshell.md
  - Memory and RAG:
    - Memory — short-term and long-term: concepts/memory.md
    - Checkpointers & Store: concepts/checkpointers.md
    - Long-term memory manager: concepts/memory-manager.md
    - RAG: concepts/rag.md
    - PgCheckpointer and retention: pg-checkpointer.md
  - Reasoning:
    - Reasoning patterns: concepts/reasoning.md
    - GSAR (typed grounding): concepts/gsar.md
    - Typed decisions: decision.md
  - Observability and serving:
    - Observability: concepts/observability.md
    - Events: concepts/events.md
    - Streaming: concepts/streaming.md
    - SSE event catalogue: concepts/sse-events.md
    - Agent server: concepts/server.md
    - Testing: concepts/testing.md
    - Evaluation: concepts/evaluation.md
  - Skills and playbooks:
    - Skills: concepts/skills.md
    - Playbooks: concepts/playbooks.md
  - Control layer:
    - Control-layer architecture: concepts/control-layer.md
    - Writing a policy that holds: concepts/policy-authoring.md
    - Guardrails: concepts/safety.md
    - SecurityContext application: concepts/security-context.md
    - Security findings (locus-sdk-security): concepts/security.md
    - Threat scenarios: concepts/threat-scenarios.md
    - Agentic AI security: concepts/agentic-ai-security.md
    - Cloud-posture agent: concepts/cloud-posture.md
  - Model providers:
    - Overview: concepts/models.md
    - OCI Generative AI: concepts/providers/oci.md
    - OCI Responses API: concepts/oci-responses.md
    - OpenAI: concepts/providers/openai.md
    - Anthropic: concepts/providers/anthropic.md
    - OpenAI-compatible endpoints: concepts/providers/openai-compatible.md
    - Resilience: concepts/providers/resilience.md
  - Research:
    - Research: research/index.md
    - Policy blindness: research/policy-blindness.md
  - Project:
    - Guarantees & boundaries: why-locus.md
    - Compatibility & releases: compatibility.md
    - About & maintainers: about.md
- How-to:
  - Quickstart: how-to/quickstart.md
  - Build it with Codex: how-to/codex.md
  - Configure a model provider: how-to/configure-providers.md
  - Environment variables: how-to/environment-variables.md
  - First controlled action: how-to/first-controlled-action.md
  - Persist conversations: how-to/persist-conversations.md
  - Build a custom tool: how-to/custom-tools.md
  - Add a checkpointer backend: how-to/custom-checkpointer.md
  - Build a security integration: how-to/build-an-integration.md
  - OCI Generative AI models: how-to/oci-models.md
  - Dedicated AI Clusters: how-to/oci-dac.md
  - LiteLLM gateway: how-to/litellm-gateway.md
  - Deploy: how-to/deploy.md
  - The box runner: runner.md
- Notebooks:
  - Examples: notebooks/index.md
  - By topic:
    - Start here:
      - 01 · OCI transports — start here: notebooks/notebook_01_oci_transports.md
      - 02 · Basic agent: notebooks/notebook_02_basic_agent.md
      - 03 · Agent with tools: notebooks/notebook_03_agent_with_tools.md
      - 04 · A chat loop: notebooks/notebook_04_chat_loop.md
      - 05 · Conversation memory: notebooks/notebook_05_agent_memory.md
      - 06 · Streaming events: notebooks/notebook_06_agent_streaming.md
      - 07 · Structured output: notebooks/notebook_07_structured_output.md
      - 08 · Termination conditions: notebooks/notebook_08_termination.md
      - 09 · Lifecycle hooks: notebooks/notebook_09_agent_hooks.md
      - 10 · Advanced hooks and guardrails: notebooks/notebook_10_hooks_advanced.md
      - 11 · Model providers: notebooks/notebook_11_model_providers.md
    - Multi-agent shapes:
      - 12 · Basic graph: notebooks/notebook_12_basic_graph.md
      - 13 · Conditional routing: notebooks/notebook_13_conditional_routing.md
      - 14 · State reducers: notebooks/notebook_14_state_reducers.md
      - 15 · Human in the loop: notebooks/notebook_15_human_in_the_loop.md
      - 16 · Advanced graph patterns: notebooks/notebook_16_advanced_patterns.md
      - 17 · Resilient graphs: notebooks/notebook_17_graph_advanced.md
      - 18 · Functional API: notebooks/notebook_18_functional_api.md
      - 19 · Composition — pipelines: notebooks/notebook_19_composition.md
      - 20 · Scatter-gather with Send: notebooks/notebook_20_map_reduce_support_triage.md
      - 21 · Supervisor and critic loop: notebooks/notebook_21_supervisor_critic_loop.md
      - 22 · Orchestrator: notebooks/notebook_22_orchestrator_pattern.md
      - 23 · Specialist agents: notebooks/notebook_23_specialist_agents.md
      - 24 · Swarm: notebooks/notebook_24_swarm_multiagent.md
      - 25 · Handoff: notebooks/notebook_25_agent_handoff.md
      - 26 · Debate with a judge: notebooks/notebook_26_debate_with_judge.md
      - 27 · Multi-agent human in the loop: notebooks/notebook_27_multiagent_human_in_loop.md
      - 28 · Emergent routing: notebooks/notebook_28_emergent_routing.md
      - 29 · Cognitive router: notebooks/notebook_29_cognitive_router.md
      - 30 · A2A protocol: notebooks/notebook_30_a2a_protocol.md
      - 31 · DeepAgent: notebooks/notebook_31_deepagent.md
      - 32 · Research workflow: notebooks/notebook_32_research_workflow.md
    - Oracle Cloud and Database 26ai:
      - 33 · OCI v1 chat: notebooks/notebook_33_oci_openai_chat.md
      - 34 · OCI Responses: notebooks/notebook_34_oci_responses.md
      - 35 · OCI Dedicated AI Cluster: notebooks/notebook_35_oci_dac.md
      - 36 · OCI tools — drive the control plane: notebooks/notebook_36_oci_tools.md
      - 37 · Oracle 26ai store: notebooks/notebook_37_oracle_store.md
      - 38 · Oracle 26ai RAG: notebooks/notebook_38_oracle_26ai_rag.md
      - 39 · Oracle ADB loader: notebooks/notebook_39_oracle_adb_loader.md
      - 40 · Oracle in-DB chunker: notebooks/notebook_40_oracle_indb_chunker.md
      - 41 · Oracle in-DB embeddings: notebooks/notebook_41_oracle_indb_embeddings.md
      - 42 · Oracle 26ai checkpointer: notebooks/notebook_42_oracle_26ai_checkpointer.md
      - 43 · Oracle versioned saver: notebooks/notebook_43_oracle_versioned_saver.md
      - 44 · Oracle agent memory: notebooks/notebook_44_oracle_agent_memory.md
      - 45 · Cohere reranker on Oracle 26ai: notebooks/notebook_45_cohere_reranker.md
    - The harness — tools, skills, memory, RAG, reasoning:
      - 46 · MCP integration: notebooks/notebook_46_mcp_integration.md
      - 47 · Plugins: notebooks/notebook_47_plugins.md
      - 48 · Skills: notebooks/notebook_48_skills.md
      - 49 · Playbooks: notebooks/notebook_49_playbooks.md
      - 50 · Checkpoint backends: notebooks/notebook_50_checkpoint_backends.md
      - 51 · RAG basics: notebooks/notebook_51_rag_basics.md
      - 52 · RAG providers: notebooks/notebook_52_rag_providers.md
      - 53 · RAG agents: notebooks/notebook_53_rag_agents.md
      - 54 · Reasoning patterns: notebooks/notebook_54_reasoning_patterns.md
      - 55 · GSAR typed grounding: notebooks/notebook_55_gsar_typed_grounding.md
      - 56 · Evaluation: notebooks/notebook_56_evaluation.md
      - 57 · Multi-modal providers: notebooks/notebook_57_multimodal_providers.md
      - 58 · Audio response: notebooks/notebook_58_audio_response.md
      - 59 · Audio chat: notebooks/notebook_59_audio_chat.md
    - Observability, streaming, serving:
      - 60 · Observability basics: notebooks/notebook_60_observability_basics.md
      - 61 · Agent yield bridge: notebooks/notebook_61_agent_yield_bridge.md
      - 62 · EventBus subscribers: notebooks/notebook_62_eventbus_subscribers.md
      - 63 · Event catalogue: notebooks/notebook_63_event_catalogue.md
      - 64 · SSE streaming: notebooks/notebook_64_sse_streaming.md
      - 65 · Agent server: notebooks/notebook_65_agent_server.md
      - 66 · LiteLLM gateway: notebooks/notebook_66_litellm_gateway.md
      - 67 · LiteLLM cost guardrails: notebooks/notebook_67_litellm_gateway_cost.md
    - Control layer and security:
      - 68 · Steering: notebooks/notebook_68_steering.md
      - 69 · Guardrails — prompt injection: notebooks/notebook_69_guardrails_security.md
      - 70 · Trace hygiene: notebooks/notebook_70_guardrails_advanced.md
      - 71 · Payment refund gate: notebooks/notebook_71_payment_refund_gate.md
      - 72 · Infra deploy gate: notebooks/notebook_72_infra_deploy_gate.md
      - 73 · Support account gate: notebooks/notebook_73_support_account_gate.md
      - 74 · Data deletion gate: notebooks/notebook_74_data_deletion_gate.md
      - 75 · Cloud resource gate: notebooks/notebook_75_cloud_resource_gate.md
      - 76 · Incident response with an audit chain: notebooks/notebook_76_ir_audit_trail.md
    - Real-world workflows:
      - 77 · Incident response runbook: notebooks/notebook_77_incident_response.md
      - 78 · Concession approval: notebooks/notebook_78_concession_approval.md
      - 79 · Contract review: notebooks/notebook_79_contract_review.md
      - 80 · Vendor integrations: notebooks/notebook_80_vendor_integrations.md
    - Security operations (locus-sdk-security):
      - 81 · Grounded cloud-posture agent: notebooks/notebook_81_cloud_posture_agent.md
      - 82 · SOC playbooks: notebooks/notebook_82_security_playbooks.md
      - 83 · Red-team an AI agent: notebooks/notebook_83_agent_red_team.md
      - 84 · Red-team a support bot: notebooks/notebook_84_redteam_support_bot.md
      - 85 · CI security gate: notebooks/notebook_85_ci_security_gate.md
      - 86 · Verify findings: notebooks/notebook_86_verify_findings.md
      - 87 · SOC alert triage: notebooks/notebook_87_soc_alert_triage.md
      - 88 · Model and hardware fingerprinting: notebooks/notebook_88_model_fingerprint.md
      - 89 · Investigate with SecurityContext: notebooks/notebook_89_investigate_with_ctx.md
- API reference:
  - Overview: api/index.md
  - Agent: api/agent.md
  - Multi-agent: api/multiagent.md
  - DeepAgent: api/deepagent.md
  - Control: api/control.md
  - Security: api/security.md
  - Tools: api/tools.md
  - A2A: api/a2a.md
  - Hooks: api/hooks.md
  - Termination: api/termination.md
  - Reasoning: api/reasoning.md
  - RAG: api/rag.md
  - Memory: api/memory.md
  - Checkpointers: api/checkpointers.md
  - Models: api/models.md
  - Capability providers: api/providers.md
  - Streaming: api/streaming.md
  - Events: api/events.md
  - Observability: api/observability.md
  - Agent Server: api/server.md
  - Evaluation: api/evaluation.md
  - Playbooks: api/playbooks.md
  - Skills: api/skills.md
  - Integrations: api/integrations.md
  - Core primitives: api/core.md
  - ReAct loop (deprecated): api/loop.md