Notebooks¶
63 runnable examples/notebook_NN_*.py files. Every one runs end-to-end
against the bundled MockModel (no credentials required) and upgrades
to live Oracle Cloud Infrastructure (OCI) Generative AI —
or OpenAI / Anthropic / Ollama — by setting one environment variable.
Run any notebook directly:
git clone https://github.com/oracle-samples/locus.git
cd locus && pip install -e .
python examples/notebook_01_oci_transports.py
The notebooks are numbered in suggested reading order. Start at 01 and walk forward; each one builds on the last. If you're shipping on OCI, the first seven are the path you came for.
01–05 · OCI Generative AI¶
The OCI inference platform end-to-end: pick a transport, point at a cluster, on-demand reranking. Start here if you're shipping on OCI.
| # | Notebook | What you get |
|---|---|---|
| 01 | OCI transports — start here | The three OCI transports side by side (V1, Responses, generic chat) |
| 02 | OCI v1 (OCIChatCompletionsModel) |
The default transport — every OCI model family in one class |
| 03 | OCI Responses (OCIResponsesModel) |
Opt-in stateful path with built-in tools |
| 04 | OCI Dedicated AI Cluster (DAC) | Wiring a private endpoint OCID into Locus |
| 05 | Cohere Reranker V4 on OCI | Retrieve-then-rerank with OCI on-demand rerank-v4 |
06–07 · Oracle Database 26ai¶
The Oracle data layer: native VECTOR(N, FLOAT32) data type and the
VECTOR_DISTANCE SQL function let your agent ground answers and
durably checkpoint conversations directly in Oracle Autonomous Database.
| # | Notebook | What you get |
|---|---|---|
| 06 | Oracle 26ai RAG | OracleVectorStore against an Autonomous Database wallet — native VECTOR(N, FLOAT32), VECTOR_DISTANCE SQL |
| 07 | Oracle 26ai checkpointer | oracle_checkpointer — resume agent conversations from ADB |
13–20 · Agent Foundations¶
The agent loop, tools, memory, streaming, hooks. Where to send a brand-new developer.
| # | Notebook |
|---|---|
| 08 | Basic agent |
| 09 | Agent with tools |
| 10 | Conversation memory |
| 11 | Streaming events |
| 12 | Lifecycle hooks |
| 13 | SSE streaming |
| 14 | Hooks (advanced) |
| 15 | Termination conditions |
16–23 · Graphs & composition¶
StateGraph, conditional edges, reducers, retries, the functional API.
24–34 · Multi-agent¶
In-process patterns plus A2A, DeepAgent, and real-world crew workflows.
| # | Notebook | Shape |
|---|---|---|
| 24 | Swarm | Peer-to-peer shared context |
| 25 | Agent handoff | Sequential escalation |
| 26 | Orchestrator pattern | Coordinator + parallel specialists |
| 27 | Specialist agents | Named domain experts |
| 28 | A2A protocol (cross-process) | HTTP + SSE mesh |
| 29 | DeepAgent — research factory | Reflexion + grounding + subagents |
| 30 | Map-reduce code review | Send fan-out / reduce |
| 31 | Supervisor + critic loop | Refinement loop with cycles |
| 32 | Adversarial debate + judge | Typed Verdict via output_schema |
| 33 | Multi-agent + human-in-the-loop | Three HITL patterns in one file |
| 34 | Emergent routing | Opt-in LLM-as-picker |
35–37 · Reasoning & structured output¶
Pydantic schemas, Reflexion, Grounding, Causal, GSAR.
| # | Notebook |
|---|---|
| 35 | Structured output (Pydantic) |
| 36 | Reasoning patterns |
| 37 | GSAR — typed grounding |
38–40 · RAG¶
| # | Notebook |
|---|---|
| 38 | RAG basics |
| 39 | RAG providers (vector stores, embeddings) |
| 40 | RAG agents |
41–45 · Skills, playbooks & plugins¶
| # | Notebook |
|---|---|
| 41 | MCP integration |
| 42 | Playbooks |
| 43 | Plugins |
| 44 | Skills |
| 45 | Steering (LLM-as-policy hook) |
46–51 · Production¶
Guardrails, checkpointers, evaluation, provider matrix, multi-modal.
| # | Notebook |
|---|---|
| 46 | Guardrails & security (basics) |
| 47 | Guardrails (advanced) |
| 48 | Checkpoint backends |
| 49 | Evaluation |
| 50 | Model providers |
| 51 | Multi-modal providers (web, images, audio) |
52–56 · Cognitive router & observability¶
Cognitive router + opt-in EventBus telemetry.
| # | Notebook |
|---|---|
| 52 | Cognitive router (PRISM) |
| 53 | Observability basics — opt-in SSE telemetry |
| 54 | Agent yield bridge + token usage |
| 55 | EventBus subscriber patterns |
| 56 | Full event catalogue tour |
57–61 · Real-world workflows¶
End-to-end use cases — incident response, contract review, audio chat.
| # | Notebook |
|---|---|
| 57 | On-call incident response |
| 58 | Tiered procurement approval |
| 59 | Contract review + negotiation |
| 60 | Voice output (TTS) |
| 61 | Voice in → voice out (gpt-audio) |
62–63 · Server & full pipelines¶
| # | Notebook |
|---|---|
| 62 | Agent server (FastAPI) |
| 63 | Research workflow (full pipeline) |