Initial commit: AI Dev Copilot — review, test & document code with Gemini

Three unified dev agents (reviewer, tester, documenter) behind one CLI,
built on Google Gemini with a shared client, unit-tested pure helpers,
packaging, and CI across Python 3.10-3.12.

Inspired by the 500-AI-Agents-Projects collection (MIT), reimplemented
from scratch on Gemini.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Meriam-Inoubli

.env.example

@@ -0,0 +1,5 @@
+# Get a free API key at https://aistudio.google.com/app/apikey
+GEMINI_API_KEY=your-key-here
+
+# Optional: override the default model (gemini-2.0-flash)
+# GEMINI_MODEL=gemini-2.0-flash

.github/workflows/ci.yaml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest -v

.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+
+# Environment
+.env
+.venv/
+venv/
+
+# Generated by the copilot (anchored to repo root so real tests/ stay tracked)
+/test_*.py
+/README_*.md
+/documented_*.py
+
+# IDE / OS
+.vscode/
+.idea/
+.DS_Store

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meriam Inoubli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,119 @@
+# 🤖 AI Dev Copilot
+
+> Review, test and document your Python code with **Google Gemini** — three developer agents in one clean CLI.
+
+[![CI](https://github.com/Meriam-Inoubli/ai-dev-copilot/actions/workflows/ci.yaml/badge.svg)](https://github.com/Meriam-Inoubli/ai-dev-copilot/actions/workflows/ci.yaml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
+[![Gemini](https://img.shields.io/badge/LLM-Google%20Gemini-8E75B2?logo=googlegemini&logoColor=white)](https://ai.google.dev/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+**AI Dev Copilot** bundles three focused agents behind a single command:
+
+| Agent | What it does |
+|-------|--------------|
+| 🔍 **Reviewer** | Structured review — bugs, security, performance, style, with concrete fixes |
+| 🧪 **Tester** | Generates a ready-to-run `pytest` suite (happy paths, edge cases, errors) |
+| 📝 **Documenter** | Writes a professional README and adds Google-style docstrings |
+
+Run them individually, or run **`all`** to review + test + document a file in one pass.
+
+---
+
+## ✨ Why this exists
+
+Most "AI agent" demos are single throwaway scripts, each reinventing its own LLM
+plumbing. AI Dev Copilot is built like a small product instead:
+
+- **One shared Gemini client** (`llm.py`) — consistent config, one place to change models.
+- **Pure, tested helpers** — AST-based structure extraction and fence-stripping are unit-tested with **no API key required**, so CI stays green and free.
+- **Zero-setup demo** — every command falls back to a bundled example file, so you can try it before wiring up your own code.
+- **Proper packaging** — installable, with a `devcopilot` entry point, `ruff` linting and CI across Python 3.10–3.12.
+
+---
+
+## 🚀 Quick Start
+
+```bash
+git clone https://github.com/Meriam-Inoubli/ai-dev-copilot.git
+cd ai-dev-copilot
+
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+
+cp .env.example .env        # then paste your free Gemini key
+```
+
+Get a free key at **[aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey)**.
+
+```bash
+# Try it instantly on the bundled demo (no --file needed)
+devcopilot review
+
+# Point it at your own code
+devcopilot review --file path/to/app.py
+devcopilot test   --file path/to/app.py --output tests/test_app.py
+devcopilot doc    --file path/to/app.py --mode readme
+devcopilot all    --file path/to/app.py
+```
+
+---
+
+## 🧑‍💻 Use it as a library
+
+```python
+from ai_dev_copilot import review_code, generate_tests, generate_readme
+
+code = open("app.py").read()
+
+print(review_code(code))               # markdown review
+open("test_app.py", "w").write(generate_tests(code, "app"))
+open("README_app.md", "w").write(generate_readme(code, "app.py"))
+```
+
+---
+
+## 🏗️ Architecture
+
+```
+src/ai_dev_copilot/
+├── llm.py          # single Gemini client (system + user prompt → text)
+├── utils.py        # pure helpers: AST outline, code-fence stripping  (unit-tested)
+├── reviewer.py     # 🔍 review_code()
+├── tester.py       # 🧪 generate_tests()
+├── documenter.py   # 📄 generate_readme() + add_docstrings()
+└── cli.py          # devcopilot: review | test | doc | all
+```
+
+Each agent is just a focused prompt over the shared client — easy to read, extend, or swap the model.
+
+---
+
+## ⚙️ Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GEMINI_API_KEY` | — | Your Gemini API key (required for live calls) |
+| `GEMINI_MODEL` | `gemini-2.0-flash` | Model override |
+
+---
+
+## 🧪 Development
+
+```bash
+pip install -e ".[dev]"
+pytest -v          # runs offline — no API key needed
+ruff check .
+```
+
+---
+
+## 🙏 Credits
+
+The three agent ideas were inspired by the excellent
+[500 AI Agents Projects](https://github.com/ashishpatel26/500-AI-Agents-Projects)
+collection (MIT). This project reimplements them from scratch on **Gemini**, unified
+into one tested, installable package.
+
+## 📄 License
+
+[MIT](LICENSE) © 2026 Meriam Inoubli

examples/sample_module.py

@@ -0,0 +1,38 @@
+"""A small sample module the copilot can review, test and document."""
+
+
+def calculate_discount(price, discount_percent):
+    if price < 0:
+        raise ValueError("Price cannot be negative")
+    if not 0 <= discount_percent <= 100:
+        raise ValueError("Discount must be between 0 and 100")
+    return price * (1 - discount_percent / 100)
+
+
+def find_longest_word(text):
+    if not text or not text.strip():
+        return ""
+    return max(text.split(), key=len)
+
+
+class ShoppingCart:
+    def __init__(self):
+        self.items = {}
+
+    def add_item(self, name, price, quantity=1):
+        if price < 0:
+            raise ValueError("Price cannot be negative")
+        if quantity < 1:
+            raise ValueError("Quantity must be at least 1")
+        if name in self.items:
+            self.items[name]["quantity"] += quantity
+        else:
+            self.items[name] = {"price": price, "quantity": quantity}
+
+    def remove_item(self, name):
+        if name not in self.items:
+            raise KeyError(f"Item '{name}' not in cart")
+        del self.items[name]
+
+    def total(self):
+        return sum(i["price"] * i["quantity"] for i in self.items.values())

pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ai-dev-copilot"
+version = "0.1.0"
+description = "Review, test and document Python code with Google Gemini — three dev agents in one CLI."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Meriam Inoubli", email = "meriam.inoubli@dauphine.tn" }]
+keywords = ["ai", "agent", "gemini", "llm", "code-review", "test-generation", "documentation", "devtools"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "google-generativeai>=0.8.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[project.urls]
+Homepage = "https://github.com/Meriam-Inoubli/ai-dev-copilot"
+Issues = "https://github.com/Meriam-Inoubli/ai-dev-copilot/issues"
+
+[project.scripts]
+devcopilot = "ai_dev_copilot.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100

requirements.txt

@@ -0,0 +1,2 @@
+google-generativeai>=0.8.0
+python-dotenv>=1.0.0

src/ai_dev_copilot/__init__.py

@@ -0,0 +1,24 @@
+"""AI Dev Copilot — review, test and document Python code with Gemini.
+
+A single, cohesive toolkit that combines three developer agents:
+
+* :func:`~ai_dev_copilot.reviewer.review_code`   — structured code review
+* :func:`~ai_dev_copilot.tester.generate_tests`  — pytest suite generation
+* :func:`~ai_dev_copilot.documenter.generate_readme` / ``add_docstrings`` — docs
+"""
+
+from __future__ import annotations
+
+from .documenter import add_docstrings, generate_readme
+from .reviewer import review_code
+from .tester import generate_tests
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "add_docstrings",
+    "generate_readme",
+    "generate_tests",
+    "review_code",
+]