This project was built as part of the AI Agents: Intensive Vibe Coding Capstone Project. Approximately 40% of the code was LLM generated, followed by heavy human review, architectural refactoring, and integration.

---

Important Links

• Kaggle Writeup — Deep dive into the project's development, optimization iterations, and capstone findings.
• YouTube Live Demo — See the dual-engine routing, CodeLens complexity markers, and offline fallback mechanism in action.

---

The Philosophy (Why I Built This)

In the era of code generators, developers often treat AI as a crutch—blindly generating files without understanding how they work under the hood. The Sniffer was built on the philosophy that AI is best used as a tool for learning and refinement, not just automation.

Instead of silently rewriting your code and introducing black-box logic, The Sniffer acts as an interactive code reviewer:

1. Educational Feedback: It pinpoints performance bottlenecks, nesting issues, and architectural anti-patterns, explaining why they matter and offering focused before/after snippets.
2. Interactive CodeLens Complexity: It injects AST-calculated Big-O complexity indicators (e.g., Time Complexity: O(n²)) directly above your function signatures inside the editor, prompting you to think about asymptotic growth before saving.
3. Abstracted Prompting: Good AI tooling shouldn't require you to write perfect prompts. The Sniffer completely abstracts prompt engineering. You simply write and save your Python code, and the extension builds the context, manages tool execution, and formats the output automatically.

---

Architecture

The Sniffer uses a dual-engine offline-resilient architecture consisting of a TypeScript VS Code extension frontend communicating with a local Python backend.

┌────────────────────────────────────────────────────────┐
│               VS Code Editor (Frontend)                │
│                                                        │
│  ┌───────────────────────┐   ┌──────────────────────┐  │
│  │   CodeLens Provider   │   │  Extension Logic     │  │
│  │ (Big-O Annotations)   │   │ (Save Listener, etc) │  │
│  └───────────┬───────────┘   └──────────┬───────────┘  │
└──────────────┼──────────────────────────┼──────────────┘
               │ (CLI JSON stdout)        │ (Spawn Process / http stream)
               ▼                          ▼
┌────────────────────────────────────────────────────────┐
│             Python ADK Backend / Local AI              │
│                                                        │
│   ┌────────────────────┐          ┌────────────────┐   │
│   │    Gemini ADK      ├─────────►│  Gemini API    │   │
│   │ (Primary Engine)   │ (Failed) │  (Cloud AI)    │   │
│   └────────────────────┴───┐      └────────────────┘   │
│                            │                           │
│                            ▼                           │
│                   ┌────────────────┐                   │
│                   │  Ollama / Qwen │                   │
│                   │  (Fallback)    │                   │
│                   └────────────────┘                   │
└────────────────────────────────────────────────────────┘

1. The VS Code Extension (localcode-optimizer-ide)

• Event Listener: Hooks into Python file save events and debounces execution (800ms window) to prevent multiple parallel runs on rapid formatting saves.
• Routing & Fallback Orchestration: Spawns the primary ADK agent process configured to use gemini-2.5-flash. If the agent fails (due to a 429 quota limit, network outage, or incorrect key), the extension catches the exit code and directly streams a token-by-token fallback review from a local Ollama instance (localhost:11434).
• Static CodeLens Provider: Spawns a lightweight Python CLI utility that parses the AST, calculates loop nesting and recursion bounds, and renders floating Big-O annotations above each function.

2. The Python Backend (localcode-optimizer)

• Gemini ADK Agent: Built using the Google ADK, coordinating custom static tools (parse_python_file, extract_code_issues) with read-only MCP FileSystem tools (pinned to a stable @0.6.2 version for zod-v3 compatibility) to review code sandbox-safely.
• AST Analysis Engine: Runs lightweight static checks using Python's native ast module to flag nested loops, bare exceptions, global variable leaks, and magic numbers without executing any code.
• Big-O Inference Visitor: Tracks recursion styles (linear vs halving recursion) and nested loops to assign worst-case time complexities.

---

Folder Structure

the-sniffer/
├── localcode-optimizer/              # Python Backend (Agent & Tools)
│   ├── app/
│   │   ├── agent.py                  # Gemini ADK agent & MCP tool configuration
│   │   ├── complexity.py             # AST Big-O inference engine
│   │   ├── complexity_cli.py         # Lightweight CLI for CodeLens integration
│   │   ├── test_integration.py       # Sandbox integration validation script
│   │   ├── tools.py                  # Code quality rules & AST analysis functions
│   │   └── __init__.py
│   ├── pyproject.toml                # UV package & dependency specifications
│   ├── Dockerfile                    # Isolated Linux runner configuration
│   ├── smoke_test.py                 # Backend sanity checks
│   ├── check_env.py                  # Local environment diagnostics
│   └── DESIGN_SPEC.md                # Project spec and design document
│
├── localcode-optimizer-ide/          # VS Code Extension Frontend (TypeScript)
│   ├── src/
│   │   └── extension.ts              # Routing logic, debouncer, & CodeLens provider
│   ├── .vscode/
│   │   ├── launch.json               # Development run configuration (injects API key)
│   │   └── tasks.json                # TypeScript pre-compilation task
│   ├── package.json                  # Extension commands & configuration settings
│   ├── tsconfig.json                 # TypeScript compiler configuration
│   └── dsa_test.py                   # Sample file for manual testing & review
│
└── logo.png                          # Beagle Logo (Save your image here!)

---

Getting Started

Prerequisites

• VS Code
• Ollama (for offline fallback capability)
• Node.js (v18+)
• uv (Astral's fast Python package manager)

---

Step 1: Set Up the Python Backend

1. Navigate to the backend directory:

   cd localcode-optimizer

2. Create and activate a virtual environment, then install dependencies:

   uv venv
   .venv\Scripts\activate
   uv pip install -e .

3. Ensure your environment loads cleanly by running the smoke test:

   python smoke_test.py

---

Step 2: Set Up Ollama (Offline Engine)

1. Open a separate terminal and start Ollama:

   ollama serve

2. Pull the lightweight coder model (used by default for rapid fallback):

   ollama pull qwen2.5-coder:0.5b

---

Step 3: Set Up and Debug the Extension

1. Open the extension folder in VS Code:

   cd ../localcode-optimizer-ide
   code .

2. Install dependencies:

   npm install

3. Open .vscode/launch.json and replace PASTE_YOUR_KEY_HERE with your Gemini API key in the env object:

   "env": {
     "GEMINI_API_KEY": "AIzaSy...",
     "GOOGLE_GENAI_USE_VERTEXAI": "False"
   }

4. Press F5 (or go to Run and Debug → Run Extension). This will compile the TypeScript code and launch a new Extension Development Host window.

---

Step 4: Run the Analyzer

1. In the Extension Development Host window, open any Python file (e.g., dsa_test.py or create your own).
2. Hover above any function definition to see the Time Complexity CodeLens.
3. Click on the CodeLens annotation to show a detail popup of the analysis.
4. Save the file (Ctrl+S) or run the command LocalCode Optimizer: Review Active File from the command palette (Ctrl+Shift+P).
5. Open the Output panel and select LocalCode Optimizer from the dropdown menu in the upper-right to watch the live review stream.