# NovaCorp Operations Assistant
### MCP + CrewAI — Week 14 Mini-Project (Futurense AI Clinic)

A multi-agent operations assistant that answers business questions by searching local documents and order records. Built with **FastMCP** (MCP server) and **CrewAI** (agents). Runs locally with a free/local LLM — no paid API required.

---

## What It Does

Given a natural-language question, a crew of three agents:
1. **Researcher** — searches NovaCorp's policy docs, product notes, and support tickets; reads order records by ID
2. **Writer** — synthesises evidence into a sourced markdown report saved to `outputs/`
3. **Critic** — cross-checks every claim in the report against the retrieved evidence

Every answer cites its source. If no evidence is found, the agent says so rather than guessing.

---

## Project Structure

```
.
├── data/
│   ├── documents/           # 10 NovaCorp policy/product/ticket docs
│   └── records.csv          # 23-row orders dataset
├── mcp_server/
│   └── server.py            # FastMCP server: 3 tools + 1 resource
├── crew/
│   ├── agents.py            # Researcher, Writer, Critic agents
│   ├── tasks.py             # Task definitions
│   └── main.py              # Crew entry point (CLI)
├── tests/
│   ├── test_tools.py        # Unit tests (no server needed) — 18 passing
│   └── test_crew_e2e.py     # End-to-end crew test
├── examples/                # 3 sample Q&A outputs with Critic verdicts
├── traces/                  # Auto-saved run traces (JSON + MD)
├── outputs/                 # Reports written by save_report tool
├── docs/                    # Original assignment brief
├── .env.example             # Copy to .env — no secrets committed
├── ai_usage_log.md          # AI tool usage + real bugs found
├── decision_log.md
├── reflection.md
└── requirements.txt
```

---

## Quick Start (Fresh Clone)

### 1. Clone and install dependencies

```bash
git clone <repo-url>
cd <repo-folder>
pip install -r requirements.txt
```

### 2. Configure your LLM

Copy `.env.example` to `.env` and choose **one** LLM backend:

**Option A — Ollama (recommended, fully local & free)**
```bash
# Install Ollama from https://ollama.com, then pull the model:
ollama pull llama3.2:3b
# Then:
cp .env.example .env   # already configured for llama3.2:3b
```

**Option B — Groq (free tier, cloud)**
```bash
cp .env.example .env
# Edit .env: uncomment GROQ_API_KEY and set your key from console.groq.com
```

**Option C — OpenAI (paid)**
```bash
cp .env.example .env
# Edit .env: uncomment OPENAI_API_KEY and set your key
```

### 3. Run the crew

```bash
python crew/main.py "What is the return policy for damaged goods?"
python crew/main.py "What is the status of order ORD-0021?"
python crew/main.py "What warranty does the NX-500 carry?"
```

The crew will:
- Connect to the MCP server automatically over stdio
- Search documents and/or read order records
- Write a sourced report to `outputs/`
- Save a run trace to `traces/`
- Ask for your approval before writing the report (unless `AUTO_APPROVE=true` in `.env`)

---

## Inspect the MCP Server

Open the MCP Inspector to verify all tools and the resource are registered:

```bash
npx @modelcontextprotocol/inspector python mcp_server/server.py
```

You should see three tools (`search_documents`, `read_record`, `save_report`) and one resource (`documents://list`).

---

## Run Tests

```bash
# Unit tests — no LLM needed
pytest tests/test_tools.py -v

# End-to-end test — requires a running LLM
pytest tests/test_crew_e2e.py -v
```

---

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `OLLAMA_MODEL` | `ollama/llama3.2:3b` | Ollama model to use |
| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama endpoint |
| `GROQ_API_KEY` | *(unset)* | Groq API key — overrides Ollama if set |
| `GROQ_MODEL` | `groq/llama3-70b-8192` | Groq model |
| `OPENAI_API_KEY` | *(unset)* | OpenAI key — overrides Ollama if set |
| `OPENAI_MODEL` | `openai/gpt-4o-mini` | OpenAI model |
| `AUTO_APPROVE` | `false` | Skip human approval gate for `save_report` |
| `USE_HIERARCHICAL` | `false` | Use CrewAI hierarchical (manager) process |

---

## Stretch Features Implemented

| Feature | How |
|---|---|
| Human approval gate | `save_report` writes approval prompt to `stderr`; operator creates `outputs/.approve` to allow (or set `AUTO_APPROVE=true`) |
| Self-check / Critic | Third agent verifies Writer's claims against evidence using `search_documents` |
| Observability | Every run saves `traces/trace_*.json` + `traces/run_report_*.md` with timing |
| Hierarchical process | Set `USE_HIERARCHICAL=true` for manager + worker process via `Process.hierarchical` |

---

## Security Notes

- All tool inputs validated with Pydantic; path traversal attempts are rejected
- No secrets committed — use `.env` only (never `.env.example` with real keys)
- `save_report` requires explicit human approval before writing to disk
- MCP server runs over stdio — only trusted local processes connect to it
- `max_iter=5` on all agents prevents runaway loops

---

## Sample Questions

1. `"What is the return policy for damaged goods?"`
2. `"What is the status of order ORD-0021?"`
3. `"What warranty does the NX-500 carry and what is its price?"`
4. `"What was the resolution for support ticket #0019?"`
5. `"When should a support ticket be escalated to Tier 3?"`