Resume Improvement Agent — Hand-Written Agentic Loop

Track: AI Systems Engineering
Scope: Milestone 1 (Full Agentic Loop) + Milestone 2 (Memory Layer & Web UI) + Milestone 3 (Harness Engineering & Resiliency Scaffolding) + Production Agentic Enhancements

An explicit, un-frameworked Python implementation of the Perceive - Reason - Act - Reflect agentic loop built specifically to suggest improvements and rewrite resume sections using the Groq API.

---

🌟 Key Architectural Highlights

• Zero Agent Frameworks: Completely free of LangChain, LlamaIndex, CrewAI, AutoGen, or similar dependencies. Built using pure Python functions interacting directly with Groq LLM.
• Strict Control Flow: Explicit, interview-defensible architecture with explicit Pydantic / dataclass schemas (PerceivedState, AgentDecision, ActionResult, ReflectionOutcome).
• Reflexion + ReAct Architecture: Interleaves deterministic tool calls (ATS keyword matching, metric/verb scoring, LLM rewriting) with a critique-driven feedback reflection cycle.
• Targeted Project & Item Isolation: resolve_target_bullet_or_section() isolates specific user-requested projects (e.g. "Agent Forge") and optimizes ONLY the relevant bullets, keeping other section items intact.
• Unformatted Fragment Reconstruction & One-Bullet-Per-Event Cohesion: reconstruct_and_structure_resume_text_llm() parses raw, line-broken multi-line text (e.g. single-word line breaks) and merges each event into a cohesive, high-impact executive bullet.
• Programmatic Deduplication & False-Experience Guardrail: Prevents duplicate items across sections and suppresses false Experience sections for hackathons/contests.
• Honest ATS Quality Auditor: ats_score_tool evaluates real action verb density, quantification metrics (ranks, team counts, problem counts), and keyword coverage for 100% genuine, un-manipulated 85–98/100 ATS scores.
• Cross-Session Episodic Memory (Milestone 2): Persistent SQLite memory store (save, recall, recall_cross_session, get_past_section_refinements) tracking style preferences, past section refinements, and historical feedback across sessions.
• Interactive UI Clarification & Reasoning Drawer: Web UI automatically streams step-by-step PRAR trace logs to the side drawer and bubbles up clarifying questions directly in the chat thread.
• Resilient Harness & Guardrails (Milestone 3): Exponential backoff with jitter retry wrapper, multi-tiered fallback handlers, token budget tracking, stuck-loop detection, and structured JSONL logging.

---

🧩 Design Patterns

This project composes three core agentic AI patterns — ReAct + Reflexion + Plan-and-Execute — alongside classical software design patterns, all hand-written without any agent framework.

Agentic AI Patterns

Pattern	Description	Where
ReAct (Reasoning + Acting)	The agent interleaves LLM reasoning with tool execution — it reasons about what to do next, executes a tool, observes the result, then reasons again. Based on the Yao et al. ReAct paper.	reason.py → act.py loop in loop.py
Reflexion	After each action, the agent self-critiques its output against a multi-axis quality rubric, scores it, and feeds that critique back into the next reasoning step. When scores stagnate, it triggers autonomous replanning. Based on the Shinn et al. Reflexion paper.	reflect.py (_detect_strategy_stagnation)
Plan-and-Execute	Before the loop starts, the LLM generates a multi-step execution plan with a named strategy. During execution, if the plan fails, revise_plan() generates an entirely new strategy autonomously.	planner.py (generate_plan, revise_plan)

Software Design Patterns

Pattern	Description	Where
Tool-Use / Function-Calling	A registry of 8+ tools (TOOL_HANDLERS) where the LLM autonomously selects which tool to invoke and with what arguments at each step.	tools.py, act.py
Pipeline / Chain-of-Responsibility	The Perceive → Plan → Reason → Act → Reflect loop is a structured pipeline where each stage transforms state and passes it forward. Tool-chaining (_execute_tool_chain) feeds one tool's output into the next.	loop.py
Strategy Pattern	The agent dynamically switches strategies at runtime (e.g., "analyze-then-rewrite" vs. "ask-user-first" vs. "direct-rewrite") based on the planner's LLM-driven assessment of the current context.	planner.py, reason.py
Decorator Pattern	The @with_retry() decorator wraps all LLM calls with exponential-backoff retry and jitter, cleanly separating resilience concerns from business logic.	harness/retry.py
Observer / Structured Logging	Every agent event (perceive, reason, act, reflect) is logged with timing and full payloads in JSONL format, acting as an observer of the loop's execution.	harness/logger.py
Memento / Episodic Memory	Past states, style preferences, and strategy outcomes are persisted to SQLite and recalled in future sessions — a Memento pattern adapted for cross-session episodic agent memory.	memory.py

---

📁 Repository Structure

.
├── config.py           # Environment loader & config.yaml parser
├── config.yaml         # Centralized runtime configuration (model, limits, retries)
├── schema.py           # Dataclasses: PerceivedState, AgentDecision, ActionResult, ReflectionOutcome
├── perceive.py         # Step 1: Normalizes raw input into structured PerceivedState
├── reason.py           # Step 2: Groq LLM call deciding next action (tool call vs finish)
├── act.py              # Step 3: Executes tool handlers (keyword match, quality scorer, rewrite)
├── reflect.py          # Step 4: Groq LLM evaluation against rubric (score, critique, completion)
├── tools.py            # Custom tool definitions, ATS quality auditor, and python handlers
├── rules.py            # Deterministic rule checks (brackets, metrics, verb density)
├── memory.py           # SQLite episodic memory store & cross-session recall
├── router.py           # Multi-intent router with pending question & ATS redirection logic
├── resume_parser.py    # Multi-section parser for typed text and PDF uploads (split_into_sections)
├── harness/            # Milestone 3 scaffolding: retry.py, fallbacks.py, logger.py, guardrails.py
├── ui/                 # Web application: app.py (FastAPI) and static/ (HTML/CSS/JS frontend)
├── prompts.py          # System prompts for Router, Reason, Reflect, Rewrite, & Reconstruction
├── loop.py             # Orchestrator functions: run_agent_loop() & run_whole_resume_loop()
├── demo.py             # Multi-case runnable demo script
├── MEMORY_DESIGN.md    # Memory architecture rationale & SQLite cross-session recall
├── HARNESS_DESIGN.md   # Harness engineering architecture & failure modes defended against
├── PATTERNS.md         # Research paper & pattern comparison (ReAct, Reflexion, CoT, ToT, LATS)
├── requirements.txt    # Dependencies (groq, python-dotenv, pydantic, fastapi, uvicorn, pyyaml)
└── README.md           # Master Documentation

---

🛠️ Installation & Setup

1. Prerequisites

• Python 3.10 or higher installed.
• A Groq API Key (get one at console.groq.com).

2. Environment Setup

python -m venv venv
# On Windows PowerShell:
.\venv\Scripts\Activate.ps1
# On Linux/macOS:
source venv/bin/activate

pip install -r requirements.txt

3. Configure API Credentials

Create a .env file in the root directory:

GROQ_API_KEY=your_groq_api_key_here
GROQ_MODEL=llama-3.3-70b-versatile
MAX_ITERATIONS=3

---

🚀 Running the End-to-End Demo & Web UI

Option 1: Terminal Demo Script

python demo.py

Runs comprehensive test cases demonstrating single-bullet optimization, cross-session memory recall, harness resilience, and multi-section paste parsing.

Option 2: Local Web UI Application

uvicorn ui.app:app --reload

Open http://127.0.0.1:8000 in your browser.

---

📄 License & LLM Disclosure

• LLM Provider: Groq API (llama-3.3-70b-versatile)
• SDK: Official groq Python SDK
• Frameworks: 0% external agent frameworks (100% plain Python control flow)