# Stock Agent  — RAG with LangChain + pgVector + Ollama

A fully local Retrieval-Augmented Generation (RAG) sample app. It loads
details about several stock-trading companies, stores their embeddings in a
**pgVector** database, and answers questions using a **local LLM served by
Ollama** — no cloud API keys, nothing leaves your machine.

```
┌──────────┐   load+split   ┌──────────────┐  embed (Ollama)  ┌───────────┐
│ data/*.md │ ─────────────▶ │  LangChain    │ ───────────────▶ │ pgVector  │
└──────────┘                 │  ingest.py    │                  │ (Postgres)│
                             └──────────────┘                  └─────┬─────┘
                                                                     │ top-k
┌──────────┐   question    ┌──────────────┐   context + prompt      │
│  you     │ ────────────▶ │  query.py     │ ◀───────────────────────┘
└──────────┘               │  (RAG chain)  │ ── Ollama LLM ──▶ grounded answer
                           └──────────────┘
```

## Tech stack
- **LangChain** — orchestration (loaders, splitter, retriever, prompt chain)
- **pgVector** — Postgres extension used as the vector store
- **Ollama** — runs the local LLM (`llama3.1`) and embedding model
  (`nomic-embed-text`)
- **MCP** — an optional server exposing the pipeline as tools to MCP clients
  like Claude Desktop (see below)

---

## Prerequisites

Install the pieces below. Commands assume Windows + PowerShell.

> **Python version:** use **Python 3.12** (or 3.11). The pinned dependencies
> in `requirements.txt` ship prebuilt wheels for these versions. On **Python
> 3.13/3.14** some packages (e.g. `numpy 1.26.4`) have no wheel yet and fall
> back to a source build that fails without a C compiler. If `py -3.12` isn't
> available, install it with `winget install Python.Python.3.12`.

### 1. Ollama (local LLM)
Download and install from https://ollama.com/download (Windows installer).
Then pull the two models this app uses:

```powershell
ollama pull llama3.1
ollama pull nomic-embed-text
```

Ollama runs a server at `http://localhost:11434` automatically after install.
Verify:

```powershell
ollama list
```

> Tip: `llama3.1` (8B) needs ~5–6 GB RAM. If low on memory, use a smaller
> model like `llama3.2:3b` and set `LLM_MODEL=llama3.2:3b` in `.env`.

### 2. Postgres with pgVector
**Option A — Docker.** Install Docker Desktop from
https://www.docker.com/products/docker-desktop/, then from this folder:

```powershell
docker compose up -d
```

That starts Postgres 16 with the pgvector extension on port 5432
(db `stockrag`, user/pass `postgres`/`postgres`).

> On Windows, Docker Desktop's engine requires **WSL2**. If WSL2 isn't
> installed, `docker compose up -d` fails with a `500 Internal Server Error`
> and nothing listens on 5432. Install it from an **admin** terminal with
> `wsl --install` (needs a reboot), or use Option B, which needs neither
> WSL2 nor Docker.

**Option B — native Postgres (no Docker/WSL2 needed).** Install Postgres 16:

```powershell
winget install PostgreSQL.PostgreSQL.16
```

The installer runs a Windows service on port 5432 with superuser
`postgres`/`postgres` — matching the defaults in `config.py`. Postgres does
**not** bundle pgvector, so install it too:

1. Download the prebuilt Windows binary matching your Postgres **minor**
   version (e.g. `vector.v0.8.3-pg16.zip` for Postgres 16.14) from
   [andreiramani/pgvector_pgsql_windows](https://github.com/andreiramani/pgvector_pgsql_windows/releases).
   *(Community-compiled — a third-party binary. If you'd rather not trust one,
   build from source with the Visual Studio C++ tools instead.)*
2. Copy its contents into your Postgres install (needs **admin**):
   `vector.dll` → `C:\Program Files\PostgreSQL\16\lib\`, and everything under
   `share\extension\` → `C:\Program Files\PostgreSQL\16\share\extension\`.

Then create the database and enable the extension (`psql` lives in
`C:\Program Files\PostgreSQL\16\bin`):

```sql
CREATE DATABASE stockrag;
\c stockrag
CREATE EXTENSION IF NOT EXISTS vector;
```

### 3. Python dependencies

Create the venv with Python 3.12 (see the version note above):

```powershell
cd C:\Users\khema\stock-rag
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

---

## Configure

```powershell
copy .env.example .env
```

Edit `.env` only if your Postgres credentials/host differ from the defaults.

---

## Run

**Step 1 — ingest the company data into pgVector** (run once, or after
changing files in `data/`):

```powershell
python ingest.py
```

**Step 2 — ask questions** using the local LLM:

```powershell
python query.py "Who is the CEO of Zenith Capital?"
python query.py "Which company does crypto market making and is not publicly listed?"
python query.py "Compare the 2024 revenue of Summit Brokerage and Meridian Securities."
```

Or interactive mode:

```powershell
python query.py
> What ticker does Meridian Securities trade under, and on which exchange?
```

Each answer is grounded strictly in the retrieved context and prints its
sources.

### Example output

![Example query output](docs/demo_output.png)

---

## The sample data
Four fictional stock-trading companies live in `data/`:

| File                     | Company                        | Ticker |
|--------------------------|--------------------------------|--------|
| `zenith_capital.md`      | Zenith Capital Markets, Inc.   | ZCM    |
| `meridian_securities.md` | Meridian Securities Group PLC  | MSG.L  |
| `apex_trading.md`        | Apex Trading Technologies Ltd. | (private) |
| `summit_brokerage.md`    | Summit Brokerage Corporation   | SMB    |

Drop in your own `.md`, `.txt`, or `.pdf` files and re-run `python ingest.py`
to expand the knowledge base.

---

## Use it from an MCP client (Claude Desktop, IDEs, …)

The same RAG pipeline is exposed as an **MCP server** ([mcp_server.py](mcp_server.py))
so any MCP client can call it as tools. Three tools are published:

| Tool                | What it does                                                        |
|---------------------|--------------------------------------------------------------------|
| `ask_companies`     | Full RAG answer (retrieve + local LLM) with sources                |
| `search_companies`  | Raw top-k retrieved chunks, no LLM — fast lookup                    |
| `list_companies`    | Lists the documents loaded in the knowledge base                   |

You must still run `python ingest.py` once first, and have Ollama + pgVector
running (the server calls them on the first tool invocation).

### Wiring it into Claude Desktop
1. Copy the sample config into Claude Desktop's config file:
   `%APPDATA%\Claude\claude_desktop_config.json`
   (use [claude_desktop_config.example.json](claude_desktop_config.example.json)
   as the template — adjust the two absolute paths if your project isn't at
   `C:\Users\khema\stock-rag`).
2. Make sure the `command` points at the venv's Python
   (`.venv\Scripts\python.exe`) so the dependencies are on the path.
3. Fully quit and reopen Claude Desktop. The `stock-rag` tools appear under
   the tools (🔧) menu.
4. Ask, e.g. *"Use stock-rag to tell me which company does crypto market
   making."* Claude will call `ask_companies` and answer from your local data.

> The server speaks MCP over **stdio**, which is what Claude Desktop and most
> IDE MCP integrations expect. The client launches the process for you — you
> don't run `mcp_server.py` yourself in normal use.

### Quick sanity check (optional)
Install the MCP Inspector and point it at the server:

```powershell
npx @modelcontextprotocol/inspector .\.venv\Scripts\python.exe mcp_server.py
```

---

## Project layout
```
stock-rag/
├─ data/                              # source documents (the RAG knowledge base)
├─ config.py                          # env-driven settings
├─ ingest.py                          # load → split → embed → store in pgVector
├─ query.py                           # retrieve → prompt → local LLM answer (CLI + importable ask())
├─ mcp_server.py                      # MCP server exposing the RAG tools
├─ docker-compose.yml                 # Postgres + pgvector
├─ claude_desktop_config.example.json # sample MCP client config
├─ requirements.txt
└─ .env.example
```

## Troubleshooting
- **`No module named 'langchain_ollama'`** (or any dependency) — you're running
  the system Python, not the venv. Activate it (`.\.venv\Scripts\Activate.ps1`)
  or call it directly: `.\.venv\Scripts\python.exe ingest.py`.
- **`Socket is not connected` / `connection refused` on 5432** — Postgres isn't
  running. Start your native Postgres service, or Docker Desktop +
  `docker compose up -d`.
- **`docker compose up` → `500 Internal Server Error`** — Docker's engine needs
  **WSL2**. Install it (`wsl --install` from an admin terminal, then reboot) or
  use native Postgres (Prerequisites → Option B).
- **`Failed to create vector extension` / `could not open extension control
  file "vector.control"`** — pgvector isn't installed into Postgres. See
  Prerequisites → Option B.
- **`pip install` fails building `numpy`** — you're on Python 3.13/3.14. Rebuild
  the venv with Python 3.12 (see the version note under Prerequisites).
- **`model 'llama3.1' not found`** — run `ollama pull llama3.1`.
- **`Ollama call failed` / connection error** — make sure the Ollama app is
  running (`ollama list` should respond).
- **Slow first answer** — the model loads into memory on first use; later
  queries are faster.