{"id":51769839,"url":"https://github.com/wooyakob/couchbase-ai-engineering","last_synced_at":"2026-07-19T23:08:21.847Z","repository":{"id":372069386,"uuid":"1275385143","full_name":"wooyakob/couchbase-ai-engineering","owner":"wooyakob","description":"AI Engineering on Couchbase. Building AI and Agentic Apps with Foundation Models. Downloadable Book, Notebooks and Example Applications.","archived":false,"fork":false,"pushed_at":"2026-07-18T17:17:30.000Z","size":6230,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-18T19:16:09.663Z","etag":null,"topics":["agent-memory","agent-orchestration","agentic-ai","ai-engineering","couchbase","couchbase-capella","couchbase-server","embedding-models","evals","langgraph","langgraph-python","llms","mcp-protocol","observability","rag","ragas","vector-database","vector-search","vector-search-engine"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wooyakob.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-20T16:09:42.000Z","updated_at":"2026-07-18T17:17:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wooyakob/couchbase-ai-engineering","commit_stats":null,"previous_names":["wooyakob/couchbase-ai-engineering"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/wooyakob/couchbase-ai-engineering","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wooyakob%2Fcouchbase-ai-engineering","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wooyakob%2Fcouchbase-ai-engineering/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wooyakob%2Fcouchbase-ai-engineering/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wooyakob%2Fcouchbase-ai-engineering/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wooyakob","download_url":"https://codeload.github.com/wooyakob/couchbase-ai-engineering/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wooyakob%2Fcouchbase-ai-engineering/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35667563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-19T02:00:06.923Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","agent-orchestration","agentic-ai","ai-engineering","couchbase","couchbase-capella","couchbase-server","embedding-models","evals","langgraph","langgraph-python","llms","mcp-protocol","observability","rag","ragas","vector-database","vector-search","vector-search-engine"],"created_at":"2026-07-19T23:08:21.184Z","updated_at":"2026-07-19T23:08:21.840Z","avatar_url":"https://github.com/wooyakob.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![AI Engineering on Couchbase](images/book_logo.png)\n\n# AI Engineering on Couchbase\nAI Engineering is the discipline of building applications with foundation models.\n\nCouchbase is the **Operational Data Platform for AI**. We released the **AI Data Plane** (AIDP) to give production agents one governed data layer for memory, context, data access, tools, traces and cache.\n\nThe AIDP includes Agent Memory, Agent Catalog, AI Functions, MCP Server, Data Processing, Vectorization and Model Service.\n\nA quick note on what it does not include out of the box:\n\n- Orchestration is handled by LangGraph but CrewAI, LlamaIndex and Strands are also supported agent frameworks.\n- Evaluation uses Ragas to run evals but eval runs are stored in Couchbase. There are alternative eval providers that'd work too.\n\nThe purpose of this Book, accompanying Notebooks and example Applications, is to make it easier to get started testing agentic workloads with Couchbase as an Agent's single data platform for knowledge, vectors, memory, tools, prompts, traces and evals.\n\nSystem complexity and fragmented data architectures act as a barrier to entry for enterprises graduating agentic projects from proof of concept to production. It is far more likely to be a problem with data than model performance.\n\nWhen an Agent is running in Production, troubleshooting across different systems requires herculean engineering effort and often the root cause can't be found, or when it is, it takes fixes across multiple systems, and careful execution without breaking things can be a headache.\n\nI hope that this book acts as a helpful starting point for building agentic applications on Couchbase, in the environment of your choice.\n\n\u003e You should run AI workloads where it makes sense for your business.\n\n### Fully Managed Environment\n![Fully Managed](images/capelladb.png)\n\n### Self Managed Environment\n![Self Managed](images/serverdb.png)\n\n---\n\n## Book Overview\nThis is a book with hands-on runnable companions. It includes 16 detailed chapters (`docs/`), 14 end-to-end notebooks (`notebooks/`), and 2 example AI applications (`apps/`), all built using the [Couchbase Python SDK](https://docs.couchbase.com/python-sdk/current/hello-world/overview.html).\n\n| # | Chapter | Covers |\n|---|---|---|\n| 1 | [AI Engineering on Couchbase](docs/01-ai-engineering-on-couchbase.md) | Introduction to AI Engineering on Couchbase. The Couchbase Stack. Why Couchbase for Agentic applications.|\n| 2 | [Couchbase Python SDK Foundations](docs/02-python-sdk-foundations.md) | Python SDK Fundamentals. KV Operations, Subdocuments, Durability, Async, Transactions. |\n| 3 | [Data Processing for AI](docs/03-data-processing.md) | Good Data Management. Handling Unstructured Data. Chunking Strategies. Data Enrichment. Data Freshness. |\n| 4 | [Embeddings \u0026 the Vectorization Service](docs/04-vectorization-service.md) | Introduction to Embeddings. Similarity Algorithms. Choosing Embedding Models. Auto Vectorisation. |\n| 5 | [Vector Search](docs/05-vector-search.md) | The Search Service. Creating Vector Indexes. Full Text Search (FTS). Hybrid Searches. Tuning Retrieval Quality. |\n| 6 | [Retrieval-Augmented Generation](docs/06-rag.md) | Grounding. RAG API. Multi Turn. Caching. |\n| 7 | [AI Functions](docs/07-ai-functions.md) | AI Enrichment. Sentiment Analysis. Masking. Completion. |\n| 8 | [The Capella Model Service](docs/08-model-service.md) | Model Caching. Guardrails. Data Co-location. |\n| 9 | [Agent Memory](docs/09-agent-memory.md) | STM. LTM. Episodic. Semantic Recall. Agent Memory SDK. |\n| 10 | [Agent Catalog](docs/10-agent-catalog.md) | Python Functions, SQL++ Query, Semantic Search, HTTP Request Tools. Semantic Tool Discovery. Git Versioning. Agent Traces. |\n| 11 | [Orchestrating with LangGraph](docs/11-orchestration-langgraph.md) | Checkpoints. Support Agent. React Agents. |\n| 12 | [The Couchbase MCP Server](docs/12-mcp-server.md) | Read Only. Claude Client. LangGraph MCP Tools. MCP Security. |\n| 13 | [Evaluating with Ragas](docs/13-evaluation-ragas.md) | Eval Metrics. Querying Evals. Evaluating Agents. Evaluating RAG. |\n| 14 | [Vector Index Architectures](docs/14-vector-index-architectures.md) | Couchbase 8. Hyperscale. Composite. Similarity Algorithms. Index Algorithms. Recall Tuning. |\n| 15 | [Structured Outputs](docs/15-structured-outputs.md) | JSON Schemas. Pydantic Models. Model Selection. |\n| 16 | [Conclusion](docs/16-conclusion.md) | Closing Thesis: Less System Complexity, One Operational Data Platform for AI. |\n\n**Author:** *Jake Wood, Solutions Engineer at Couchbase*\n**v1 Published:** *July 18, 2026*\n\nThe latest version of the Book, **AI Engineering on Couchbase**, can be downloaded as a PDF [here](https://github.com/wooyakob/couchbase-ai-engineering/releases/tag/book-pdf-latest) for reading offline.\n\nThe contents of this book can be shared and paraphrased, but not copied verbatim and claimed as your own, under copyright.\n\n© 2026 Jake Wood.\n\n---\n## The Notebooks\nEach notebook is the runnable form of one or more chapters.\n\n1. [`01_python_sdk_quickstart`](notebooks/01_python_sdk_quickstart.ipynb): Connect, provision, KV/subdoc/TTL, SQL++\n2. [`02_vector_search_fundamentals`](notebooks/02_vector_search_fundamentals.ipynb): Chunk → embed → index → semantic/hybrid/prefiltered search\n3. [`03_rag_pipeline`](notebooks/03_rag_pipeline.ipynb): RAG chain, exact + semantic caching, conversational RAG\n4. [`04_ai_functions`](notebooks/04_ai_functions.ipynb): SQL++ AI functions (Capella) + the portable equivalent\n5. [`05_model_service`](notebooks/05_model_service.ipynb): Capella Model Service: chat, embeddings, cache, guardrails\n6. [`06_agent_memory`](notebooks/06_agent_memory.ipynb): Session store, memory store, extraction, hygiene\n7. [`07_agent_catalog_langgraph`](notebooks/07_agent_catalog_langgraph.ipynb): Cataloged tools/prompts + durable LangGraph agent\n8. [`08_ragas_evaluation`](notebooks/08_ragas_evaluation.ipynb): Score the RAG pipeline, store runs, regression queries\n9. [`09_agent_memory_managed`](notebooks/09_agent_memory_managed.ipynb): The managed Agent Memory server + SDK (the Ch. 9 §9.7–§9.8 track; needs a running Agent Memory Docker container)\n10. [`10_structured_outputs`](notebooks/10_structured_outputs.ipynb): Pydantic-verified JSON generation, synthetic data, stored/queried in Couchbase (Ch. 15)\n11. [`11_vector_index_architectures`](notebooks/11_vector_index_architectures.ipynb): Hyperscale \u0026 Composite vector indexes, recall/latency tuning, quantization tradeoffs (Ch. 14; needs **Couchbase Server / Capella 8.0+**)\n12. [`12_mcp_server`](notebooks/12_mcp_server.ipynb): Connect to the Couchbase MCP server, call a tool directly, wire it into a LangGraph agent (Ch. 12; needs [`uv`](https://docs.astral.sh/uv/) for `uvx`)\n13. [`13_eventing`](notebooks/13_eventing.ipynb): Deploy an Eventing function that reactively keeps derived AI data fresh on source mutation (Ch. 3 §3.6; needs the **Eventing service** enabled)\n14. [`14_analytics_agent_tool`](notebooks/14_analytics_agent_tool.ipynb): Enable Analytics on a collection, run an aggregate usage report, hand it to an agent as a tool (Ch. 1, 10, 11; needs the **Analytics service** enabled)\n\nNotebooks are generated from `notebooks/src/*.py` (jupytext percent format) via `python scripts/build_notebooks.py`. Edit the sources, not the `.ipynb`.\n\n---\n\n## The Apps\n- **[`apps/rag-api`](apps/rag-api/)**. FastAPI RAG service: hybrid retrieval with tenant prefilters, query condensation, Couchbase-backed chat history, and every interaction logged for evaluation.\n- **[`apps/support-agent`](apps/support-agent/)**. LangGraph support agent with Agent Catalog tools/prompts, user memory via the managed Agent Memory server + SDK, Couchbase checkpoints, optional MCP tools, and a pytest eval suite.\n\n---\n\n## Setup and Testing Requirements\n### Setup\nAll functionality can be run using a paid Capella cluster that meets the prerequisites for AI capabilities such as AI Functions and Agent Catalog. See [AI Functions Prerequisites](https://docs.couchbase.com/ai/build/ai-functions.html#prerequisites) and [Agent Catalog Prerequisites](https://docs.couchbase.com/ai/build/integrate-agent-with-catalog.html#prerequisites).\n\nYou can create a free Capella cluster with Data, Index, Query and Search enabled. AI Functions can't be tested but the remaining functionality should work as expected based on the prerequisites.\n\n### Testing\nEvery notebook is covered by an automated end-to-end suite (`pytest tests/test_notebooks.py`, executing each notebook for real, cell by cell, against a live cluster and model API) and has also been run through manually.\n\nAll 14 notebooks are verified against both **Couchbase Server 8.0+** and **Capella 8.0+**, the two backends this repo treats as equivalent, provided the Eventing and Analytics services are enabled (needed by notebooks 13 and 14). See the Quickstart's Server/Capella breakdown for the handful of Capella-only features.\n\n### Troubleshooting\nSomething failing? [`docs/troubleshooting.md`](docs/troubleshooting.md) covers the common errors across every notebook and app. Connection/auth failures, index bucket-not-found, model errors, Agent Catalog, and the Agent Memory Docker setup.\n\n---\n\n## Quickstart\n\n```bash\ngit clone \u003cthis repo\u003e \u0026\u0026 cd ai-engineering\npython3.12 -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -r requirements.txt\n\ncp .env.server.example .env.server    # local Couchbase. Fill it in.\ncp .env.capella.example .env.capella  # Capella. Fill it in.\n\nENV_FILE=.env.server jupyter lab notebooks/  # or ENV_FILE=.env.capella.\n```\n\n**Server or Capella, your choice. Most notebooks run against either.** `.env.server.example` and `.env.capella.example` are two complete, parallel configs (cluster connection, model provider, Agent Memory, Agent Catalog). Fill in whichever you'll use, then pick one per run by setting `ENV_FILE` before launching: every `load_dotenv()` call in this repo reads\n`os.getenv(\"ENV_FILE\", \".env\")`, so unset `ENV_FILE` still falls back to a plain `.env` if you'd rather manage one file yourself.\n\n**Running both at once:** `ENV_FILE` is a normal process environment variable, so two separate processes with different values are fully isolated: nothing gets overwritten.\n\nStart two Jupyter instances on different ports, each in its own terminal:\n\n```bash\nENV_FILE=.env.server  jupyter lab --port 8888 notebooks/\nENV_FILE=.env.capella jupyter lab --port 8889 notebooks/\n```\n\nEach notebook's kernel inherits whichever `ENV_FILE` its Jupyter process was started with. The same applies to `apps/rag-api` and `apps/support-agent`. This also extends to the Agent Memory server: run two containers, one per backend, on different host ports. See `.env.server.example` / `.env.capella.example` for the matching `docker run` commands (8081 vs 8080, so they don't collide either).\n\n**Capella is required, not optional, for four things**. No local Couchbase equivalent.\n\n1. **Chapter 8 / notebook 05: Model Service**: hosted models are a Capella feature.\n2. **Chapter 10-11 / notebook 07: Agent Catalog UI**: the visual catalog browser lives in the Capella console (the `agentc` CLI/SDK itself works against either backend).\n3. **Chapter 7 / notebook 04: Couchbase AI Functions**: `ai_sentiment`/`ai_summary` are Capella SQL++ functions.\n4. **Chapter 3-4: Data Processing / Vectorization workflows**: the managed extract-chunk-embed-index pipeline is a Capella AI Services feature; DIY equivalents (used elsewhere in this repo) work on either backend.\n\nEverything else (notebooks 01, 02, 03, 06, 08, 09, and both apps/) runs the same against a local Couchbase Server or Capella; just point `.env` at whichever.\n\nYou need a Couchbase cluster with Data + Query + Index + Search services and a bucket named `ai`: [Capella](https://cloud.couchbase.com/), or locally.\n\n```bash\ndocker run -d --name cb -p 8091-8097:8091-8097 -p 11210:11210 couchbase:enterprise\n```\n\n**You must create the `ai` bucket yourself** in the Couchbase Server or Capella UI before running notebook 01. It is not created for you.\n\nNotebook 01 only provisions the scopes/collections *inside* an existing bucket. On Couchbase Server: `http://localhost:8091` → Buckets → Add Bucket → name it `ai`. On Capella: your cluster → Data Tools / Buckets → Create Bucket → name it `ai`.\n\n\u003e **Single-node Docker caveat:** a single `docker run couchbase:enterprise` container is one node. If you leave \"Enable replicas\" checked when creating the bucket, the UI will warn \"you do not have enough data servers... to support this number of replicas\": there's nowhere to put the replica copy. Uncheck replicas (or set the count to 0) for a single-node bucket, or add more `couchbase:enterprise` containers to the same cluster if you want replication.\n\nModels default to OpenAI (`OPENAI_API_KEY`); set `CAPELLA_AI_ENDPOINT` to switch every notebook and app to Capella-hosted models (Chapter 8). Keep `OPENAI_API_KEY` set either way if you run the Agent Memory server (Ch. 9 §9.7): it uses OpenAI internally for its own fact extraction and embeddings.\n\n---\n\nFeedback is welcomed and encouraged.\n\n- You can email me personally at **jake_wood@mac.com**.\n- You can also raise issues, or submit PRs for review in this GitHub repo (see [contributing.md](./contributing.md)).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwooyakob%2Fcouchbase-ai-engineering","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwooyakob%2Fcouchbase-ai-engineering","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwooyakob%2Fcouchbase-ai-engineering/lists"}