GenAI Lab

GenAI Lab is a TypeScript playground for building controlled GenAI workflows with:

• Retrieval-Augmented Generation (RAG) over a local knowledge base
• LangGraph-based agent planning and routing
• MCP (Model Context Protocol) tools/resources/prompts
• bounded, safe fallback behavior

It is intentionally compact so the mechanics stay inspectable end-to-end.

---

Neat project description

GenAI Lab demonstrates a practical pattern for safe AI agents: it separates decision (LLM-planned routing) from execution (typed nodes for retrieval, drafting, answering, and finalization), and exposes the same core capabilities through a direct CLI and an MCP server interface.

---

What the project includes

• agent flow (LangGraph)

  • plans a response path based on a user request
  • retrieves notes when needed
  • drafts a message or answers a question from retrieved context
  • retries retrieval once when first pass yields insufficient context
  • returns deterministic fallback responses when appropriate

• RAG utilities

  • local semantic search over notes using OpenAI embeddings
  • source-grounded answers with [note_x] citations

• MCP surface

  • search_notes tool
  • answer_from_notes tool
  • notes://all resource
  • rag_answer_prompt prompt template

---

Repository layout

lib/
  agent/
    agent-state.ts      # LangGraph state schema
    mini-agent.ts       # LangGraph graph + nodes + routing
  embedding.ts          # Embedding helpers
  knowledge-base.ts     # In-memory note dataset
  rag-types.ts          # Shared RAG types
  retrieve-context.ts   # Retrieval filtering/threshold flow
  rag-answer.ts         # Standalone RAG answer generation
  semantic-search.ts    # Embedding + cosine similarity search
  vector-utils.ts       # Cosine similarity implementation

mcp/
  server.ts            # MCP server + tools/resources/prompts
  client-test.ts       # Script to test server tools/resources/prompts
  llm-client-test.ts   # Script showing LLM tool selection via MCP

scripts/
  agent.ts             # Run the LangGraph mini agent
  rag.ts               # Run standalone RAG answer flow
  semantic-search.ts    # Run semantic search directly

---

Setup

Requirements:

• Node.js 18+
• pnpm

pnpm install

Create .env.local at the repository root:

OPENAI_API_KEY=your_openai_api_key

Both completion and embedding calls use OpenAI:

• gpt-4.1-mini for planning/answering/drafting
• text-embedding-3-small for semantic search

---

Usage

Run the mini agent

pnpm agent "Can you explain why retrieval should happen before generation?"

Output includes the full final state and finalResponse.

Run standalone RAG

pnpm rag "Why do long chats become more expensive?"

Run semantic search

pnpm semantic-search "backend tool execution"

Start MCP server

pnpm mcp:server

Runs over stdio and exposes tools/resources/prompts defined in mcp/server.ts.

MCP integration checks

pnpm mcp:test        # raw tool/resource/prompt client checks
pnpm mcp:llm         # LLM-driven MCP tool-calling demo

---

How the agent flow works

1. Planner (planner): maps request intent into an execution plan (retrieve_notes, answer_question, draft_message, final_response).
2. Retrieve (retrieveNotes): runs similarity retrieval when required.
3. Draft/Answer (draftMessage / answerQuestion):
   • drafts a Slack-style message
   • or answers using only retrieved notes, with citations
4. Retry policy:
   • if first retrieval is empty and this is the first attempt, retry once with a broader query and lower threshold
5. Finalize (finalize): returns drafted output, RAG answer, retrieved context, or a bounded fallback.

The state machine is intentionally explicit and inspectable:

START -> planner
  ├─> retrieveNotes -> answerQuestion -> finalize
  ├─> retrieveNotes -> draftMessage -> finalize
  ├─> draftMessage -> finalize
  └─> finalize

---

Design principles implemented

• Controlled output quality: tool use and response style are constrained by explicit system prompts.
• No side-effect leakage: the planner only decides plan, all actions are backend nodes.
• Source grounding: answers can cite only known sources ([note_#]).
• Bounded behavior: retries are limited and unsupported requests take a safe fallback path.

---

Notes on MCP and agent parity

The LangGraph flow and MCP tools use the same underlying retrieval/RAG primitives:

• semantic search logic lives in lib/semantic-search.ts
• answer generation logic lives in lib/rag-answer.ts
• note store is shared in lib/knowledge-base.ts

This allows you to compare:

• in-repo agent orchestration (pnpm agent)
• direct function style RAG (pnpm rag)
• tool-based orchestration (pnpm mcp:llm)

---

Future improvements

• Persist notes in a real vector database
• Add chunking and richer document metadata
• Add confidence thresholds + eval snapshots
• Add contract tests for planner routing and retrieval fallback

---

Quality checklist

• pnpm typecheck validates strict TypeScript compilation.
• pnpm format formats all files with Prettier.