🟡 TraceAI — Transparent AI Agent with Tool Reasoning

TraceAI is a framework-free, autonomous AI agent system that implements the ReAct (Reason + Act) paradigm from scratch. It features strict output parsing, multi-step tool execution, and complete execution trace visibility via a Next.js frontend, providing a transparent, controllable, and debuggable AI experience.

---

🎯 Key Features

• Framework-Free: Built without black-box agent frameworks (like LangChain or AutoGen) to ensure complete understanding and control over the agent loop.
• Strict Output Parsing: Uses rigid schema validation to prevent LLM hallucinations and parse reasoning traces robustly.
• Multiple Tools: Includes basic tools (Calculator, Wikipedia) and advanced tools (Web Search, In-depth Research) for multifaceted agent capabilities.
• Full Observability: The Next.js frontend provides a real-time, step-by-step reasoning trace (Thought ➔ Action ➔ Input ➔ Observation).
• Error Resiliency: Auto-retries on format errors or tool failures, with safety constraints (max_steps, safe AST evaluation).

---

🏗️ System Architecture & Design

High-Level Flow

flowchart TD
    A[User Input] --> B[Next.js Frontend]
    B --> C[FastAPI Backend /chat]
    C --> D[Agent Controller Loop]
    
    subgraph Agent Loop
    D --> E[Prompt + History]
    E --> F[LLM Client Gemini]
    F --> G{Output Parser}
    G -- Invalid --> H[Retry with Error Correction]
    H --> E
    G -- Valid Action --> I[Tool Executor]
    I --> J[Observation]
    J --> E
    G -- Final Answer --> K[Return Final Output]
    end
    
    K --> L[UI Trace Renderer]

Loading

Core Components

1. Frontend (Next.js & React): Provides a conversational UI to visualize the real-time reasoning trace of the agent, rendering complex intermediate steps cleanly.
2. Backend API (FastAPI): Exposes streaming and synchronous REST endpoints for chat interaction and tool listing.
3. Agent Loop (agent/loop.py): The orchestrator. Manages state, bounds maximum steps and retries, appends history, and passes data to the LLM.
4. Output Parser (agent/parser.py): Strictly regex-extracts and validates Thought, Action, Action Input from the LLM to ensure structural integrity.
5. Tool Registry (tools/): Safely maps LLM-requested actions to underlying Python functions (e.g., using ast parsing for safe math calculation).

---

🚀 Getting Started Locally

Prerequisites

• Node.js 18+
• Python 3.9+

Backend Setup

1. Navigate to the backend directory:

   cd backend

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Create a .env file in the backend folder and add your Gemini API Key:

   GEMINI_API_KEY=your_google_gemini_api_key_here

5. Run the server:

   python main.py
   # Or using uvicorn: uvicorn main:app --reload

Frontend Setup

1. Navigate to the frontend directory:

   cd frontend

2. Install dependencies:

   npm install

3. Create a .env.local file (optional, defaults to localhost:8000):

   NEXT_PUBLIC_API_URL=http://localhost:8000

4. Start the dev server:

   npm run dev

Built for transparency, designed for production.