(#) Gemini AI Agent

A small, local-first AI code agent that uses Google's Gemini API for model calls with a robust local fallback (Ollama and heuristics). The agent exposes a set of safe file tools (list, read, write, execute) and demonstrates an LLM-driven tool-usage feedback loop for iterative bug fixing and code changes.

---

Features

• Use Gemini LLM for planning and function-calling (if API quota allows).
• Local fallback path using ollama and deterministic heuristics when Gemini is unavailable.
• Tool APIs exposed to the model:
  • get_files_info — list files and directories (restricted to project workspace)
  • get_file_content — read files with truncation safeguards
  • write_file — write or overwrite files (with directory creation and path validation)
  • run_python_file — run Python scripts and capture stdout/stderr
• Bounded agent loop that iterates on a task (up to 20 iterations) and appends tool results to conversation history.

Requirements

• Python 3.11+ (project uses 3.13 in the dev environment)
• pip and a virtual environment (recommended)
• Optional: ollama CLI installed for local LLM fallback
• A Gemini API key stored in a local .env file as GEMINI_API_KEY (only required to use Gemini)

Quickstart

1. Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Copy the env template and add your Gemini key (do NOT commit .env):

cp .env.template .env
# Edit .env and set GEMINI_API_KEY

3. Run the agent (example):

uv run main.py "how does the calculator render results to the console?" --verbose

4. Run the calculator directly:

uv run calculator/main.py "3 + 7 * 2"

Development notes

• The agent injects a working_directory (./calculator) into function calls to sandbox file operations.
• The system prompt is in prompts.py and instructs the model to prefer tool usage for code changes.
• Local heuristics and an Ollama fallback exist in main.py to allow continued functionality when Gemini API calls fail due to quota.

Security

• .env is ignored in .gitignore. Never commit secrets. Use .env.template to share required environment variables.
• If you previously pushed secrets to a remote, consider using git filter-repo or BFG to remove them from history before sharing the repository.

Tests

• Lightweight tests and helper scripts exist (see test_*.py). You can run the unit scripts directly or via the agent.

Contributing

• Open issues and PRs are welcome. Keep changes small and focused; prefer unit tests for bug fixes.

License

• MIT