🤖 Autonomous AI Agent → Word Document Generator

Give it one sentence. It plans its own tasks, does them, and hands you a polished Microsoft Word document.

An autonomous agent that understands a natural-language request, plans its own execution, grounds itself in company knowledge via RAG, writes each section with an LLM, and produces a professional .docx — all behind a clean FastAPI endpoint.

---

✨ Highlights

• 🧠 Truly autonomous — the agent designs its own task list & document structure per request (no fixed templates).
• 📚 Simple RAG — grounds every document in real company docs using local TF-IDF retrieval (no vector DB, no external service).
• 🔍 Self-checking — a reflection pass lets the agent catch and add a missing section before writing.
• 🛡️ Production-minded — request validation, safety guardrails, retry with backoff, and an offline fallback so it never hard-crashes.
• 📝 Polished output — styled Word documents (cover, metadata table, assumptions, headings, bullets, footer).
• 🧾 Fully typed — Pydantic contracts end-to-end; defensive JSON parsing of LLM output.
• ✅ Runs with zero setup — works offline in mock mode; add a free Groq key for real AI-authored prose.

---

🎬 What it does

        POST /agent  { "request": "Create a project plan for our new mobile app" }
                                     │
                                     ▼
   ┌──────────────────────────────────────────────────────────────────┐
   │                      AutonomousAgent.run()                        │
   │                                                                    │
   │  1. 🛡️  GUARDRAILS   validate & sanitise the request               │
   │  2. 📚  RETRIEVE      RAG: pull relevant company knowledge  ◄── Simple RAG
   │  3. 🧠  PLAN          LLM designs doc type + section list   ◄── Multi-step planning
   │  4. 🔍  REFLECT       self-check: any missing section?             │
   │  5. ⚙️   EXECUTE       write each section (grounded on RAG)         │
   │  6. 📝  ASSEMBLE      render a polished .docx (python-docx)         │
   └──────────────────────────────────────────────────────────────────┘
                                     │
      returns: self-generated task list + summary + assumptions + .docx

Every planned step is tracked as a TaskStep with a live status (pending → done / failed), so the API returns the agent's actual TODO list — exactly what an autonomous agent should expose.

---

🗺️ Architecture

Layer	Responsibility	Tech
1 · Input	POST /agent accepts {"request": "..."}	FastAPI
2 · Validation	length/blank checks + prompt-injection & safety filter	Pydantic v2
3 · RAG	retrieve top-k relevant chunks from knowledge/	TF-IDF + cosine (pure Python)
4 · Planning	design doc type, title, sections, assumptions	Groq · Llama 3.3 70B
5 · Reflection	self-check the plan, add a missing section	LLM critic
6 · Execution	write each section via the tool registry	write_section tool
7 · Parsing	strip fences, extract & validate JSON	_safe_json + Pydantic
8 · Reliability	retry with backoff, offline mock fallback	custom LLMClient
9 · Document	render polished Word file	python-docx
10 · Output	task list + summary + download link	FastAPI response

📎 A visual version of this diagram (with the full tech stack and reasoning) is in ARCHITECTURE.html — open it in any browser.

---

🚀 Quick start

# 1. Install
pip install -r requirements.txt

# 2. (Optional) add a FREE Groq key for real AI prose — runs offline without it
cp .env.example .env      # paste a key from https://console.groq.com/keys

# 3a. Run the two demo test cases (best for a quick look)
python demo.py

# 3b. …or start the API
python run.py             # → http://127.0.0.1:8000/docs  (interactive Swagger UI)

Call the API:

curl -X POST http://127.0.0.1:8000/agent \
  -H "Content-Type: application/json" \
  -d '{"request":"Create a project plan for launching our retail mobile app"}'

The response includes the task list and a download_url for the generated .docx (also saved in outputs/).

---

🧩 API reference

Method	Endpoint	Description
POST	/agent	Run the agent on a request; returns task list, summary & document link
GET	/download/{filename}	Download a generated .docx
GET	/health	Liveness + which LLM provider is active
GET	/	Redirects to the interactive docs

Example response (click to expand)

{
  "request": "Create a project plan for launching our retail mobile app",
  "doc_type": "Project Plan",
  "title": "Northwind One Mobile App Launch Project Plan",
  "message": "Completed a 'Project Plan' … across 8 sections in 9.8s.",
  "assumptions": ["Timeline assumes a standard business quarter …"],
  "task_list": [
    {"id": 1, "description": "Retrieve relevant company knowledge (RAG)", "tool": "knowledge_base", "status": "done"},
    {"id": 2, "description": "Analyse request and design document plan", "tool": "plan_document", "status": "done"},
    {"id": 3, "description": "Self-check plan for missing sections", "tool": "reflect_on_plan", "status": "done"},
    {"id": 4, "description": "Write section: Executive Summary", "tool": "write_section", "status": "done"}
  ],
  "download_url": "/download/northwind-one-mobile-app-launch-project-plan.docx",
  "provider_used": "groq"
}

---

🏆 The two engineering improvements

The assignment requires one. This project implements the primary one thoroughly and adds a second, plus supporting robustness.

1️⃣ Primary — Multi-step planning

The agent does not follow a hard-coded template. It calls the LLM to design its own plan for each request — the document type, title, audience, and the exact set of sections — then executes that plan step-by-step, tracking status per step.

• Generalises — one codebase makes a project plan, SOP, technical design, meeting minutes, etc.
• Handles ambiguity — for vague/conflicting requests it records the assumptions it made.
• Observable — the plan becomes a task list with per-step status.
• Adaptive — a reflection pass adds a missing section before writing.

2️⃣ Second — Simple RAG

Before planning, the agent retrieves the most relevant chunks from a local knowledge/ corpus (company profile, brand style guide, product & ops facts) and injects them into the prompts.

Proof it works: an AI-chatbot request produces a Technical Design Document that automatically includes a "Data Privacy & Security" section — because the retrieved brand style guide mandates it for technical designs. The agent grounded its structure in retrieved policy, not guesswork.

🧰 Supporting robustness

• Retry & fallback — retries transient LLM failures with backoff; falls back to a deterministic mock so the pipeline always completes.
• Guardrails — Pydantic request validation + a prompt-injection/safety check.

---

📚 How the RAG works (in plain terms)

Your request  ─►  chunk the knowledge/ files  ─►  score each chunk (TF-IDF)
      ─►  pick the top-3 most relevant  ─►  inject as "COMPANY KNOWLEDGE" in the prompt
      ─►  the LLM writes grounded in real facts & rules

Swap the three mock files in knowledge/ for a real company's documents and the agent grounds every output in them — no code change needed. The Retriever interface is intentionally small so the scorer can be upgraded to dense embeddings later.

---

🧱 Tech stack — and why

Concern	Choice	Why
Web API	FastAPI + Uvicorn	Async, typed, free Swagger docs
LLM	Groq · Llama 3.3 70B	Free, extremely fast, no credit card
LLM calls	requests (direct REST)	No LangChain weight — lighter & fully explainable
Validation / typing	Pydantic v2	Free validation + typed structured output
RAG	TF-IDF + cosine (pure Python)	Local, deterministic, zero heavy deps
Document	python-docx	Programmatic, styled .docx
Reliability	retry + mock fallback	Degrade-don't-crash
Tests	pytest (mock mode)	Deterministic, fast, free

---

📁 Project structure

Autonomus_AI_Agent/
├── app/
│   ├── main.py        # FastAPI app — /agent, /download, /health
│   ├── agent.py       # Plan → Reflect → Execute orchestrator + guardrails
│   ├── tools.py       # Tool registry: plan_document, write_section, reflect_on_plan
│   ├── rag.py         # Simple RAG — TF-IDF retriever over knowledge/
│   ├── llm.py         # Provider abstraction (Groq/Gemini/mock) + retry + fallback
│   ├── docgen.py      # Polished .docx rendering (python-docx)
│   ├── schemas.py     # Typed Pydantic contract
│   └── config.py      # Env-based settings; auto-selects mock when no key
├── knowledge/         # Company-context docs the agent retrieves from (RAG)
├── tests/             # Pytest smoke + unit tests (no API key needed)
├── demo.py            # Runs the two required test cases
├── run.py             # Launcher → http://127.0.0.1:8000/docs
├── ARCHITECTURE.html  # Visual architecture + tech-stack diagram
└── requirements.txt

---

🧪 Testing

python -m pytest -q      # 7 tests — deterministic, run in mock mode, no key required

Covers request validation, the guardrail, plan generation, RAG retrieval & ranking, document creation on disk, and the defensive JSON parser.

---

🐞 Debugging insight

Problem: the planner asks the LLM for strict JSON, but models sometimes wrap it in ```code fences or prepend prose like "Here is your plan" — crashing json.loads and the whole run.

Root cause: LLM output format is not guaranteed.

Fix: a defensive parser (_safe_json) that strips fences, and if that fails, extracts the substring between the first { and last }; returns {} as a last resort instead of crashing.

Lesson: treat LLM output as untrusted and parse it defensively.

---

⚖️ Key tradeoff — autonomous planning vs. fixed workflow

A fixed template is fast and 100% predictable, but can't handle document-type variety or ambiguity. This project chose an LLM planner for adaptability, then bounded its non-determinism with typed schemas, defensive JSON parsing, a self-check pass, and a mock fallback — keeping the flexibility while making it safe and reliable.

---

🔮 Future improvements

• Swap TF-IDF for dense embeddings + a vector store for larger corpora.
• Conversation memory for multi-turn document refinement.
• Streaming progress of the task list over WebSockets.
• Export to PDF / templated brand themes.

---

📄 License

MIT — free to use and adapt.

Built to demonstrate autonomous agent design, planning & reasoning, tool orchestration, RAG, and clean API engineering.