Skip to content

README.md

Latest commit

 

History

History
144 lines (109 loc) · 5.42 KB

README.md

File metadata and controls

144 lines (109 loc) · 5.42 KB

Simple Agent

CI

A tiny, KISS-friendly command line agent that can talk to either OpenAI's ChatGPT API or Google's Gemini API. The agent supports a pluggable backend, a light tool loop, and environment-driven configuration.

Architecture

flowchart TD
    subgraph ConfigChain[Configuration precedence]
        A1[CLI params] --> A2[.env values]
        A2 --> A3[Code defaults]
    end
    ConfigChain --> CLI
    CLI --> Prompt[Prompt task input]
    Prompt --> SystemPrompt[System prompt with tool inventory]
    SystemPrompt --> Backend{{LLM backend}}
    Backend <--> B1[OpenAI API]
    Backend <--> B2[Google Gemini API]
    Backend <--> Loop{{AGENT}}
    Loop <-->|tool call --max-turns default 5 | Tools[Tools]
    Tools --> T1[time]
    Tools --> T2[calculator]
    Tools --> T3[file_reader]
    Tools --> T4[python sandbox]
    Loop --> Response[Final response to user]
Loading

Examples

Disk space:

| => python main.py "get disk space on current machine using python"
Disk Space:
Total: 926.35 GB
Used: 452.60 GB
Free: 473.76 GB

CPU usage:

| => python main.py "give current cpu usage" -v
INFO: Running tool 'python'.
INFO: Responding without tool use.
Current CPU usage: 16.5%

LLM encoded info:

| => python main.py "captial of poland"
Warsaw

Real time search:

| => python main.py "search on wiki for top article of today? use python requests"
Top articles on English Wikipedia for 2025-11-06 (most recent complete day):
1. Zohran Mamdani (Views: 1605850)
2. Marshawn Kneeland (Views: 743737)
3. Rama Duwaji (Views: 624732)
4. Mira Nair (Views: 526808)
5. Mahmood Mamdani (Views: 383660)

Make targets (uvx-powered)

The repo ships with a lightweight Makefile wired to uvx for reproducible tooling:

  • make venv – create a local virtual environment at env/ (activate with source env/bin/activate).
  • make install – install dependencies (uses env/bin/python if make venv ran, otherwise falls back to uvx python).
  • make run PROMPT="hello" – run the agent with the provided prompt.
  • make tools – list the currently wired tools.
  • make lint – run Ruff via uvx (no local install required).

Quick start

  1. Create a virtual environment for Python 3.11+ and install the dependencies: 
    make install
  2. Copy .env.example to .env and fill in the API keys you plan to use.
  3. Run the agent: 
    make run PROMPT="Summarize the latest message."

Configuration

All settings live in .env (loaded with python-dotenv):

Variable Description
LLM_BACKEND chatgpt or gemini.
OPENAI_API_KEY Required for the ChatGPT backend.
OPENAI_MODEL Defaults to gpt-4o-mini.
GEMINI_API_KEY Required for the Gemini backend.
GEMINI_MODEL Defaults to gemini-2.5-flash.
AGENT_SYSTEM_PROMPT Optional custom system prompt.
REQUEST_TIMEOUT Request timeout in seconds (default 30).
PYTHON_TOOL_IMPORTS Optional comma list of extra python-tool imports (os,sys,psutil,bs4).

To obtain a Gemini API key, head to Google AI Studio, create a key (or use an existing Google Cloud project), and paste it into GEMINI_API_KEY. Keys can be revoked or rotated from the same page.

The repository already contains .env.example with placeholders for these values.

CLI options

python main.py --help
  • prompt (positional): user message. If missing, you will be prompted in the terminal.
  • --backend: override the backend without touching .env.
  • --max-turns: maximum number of tool iterations.
  • --no-tools: disable tool use.
  • --list-tools: inspect available tools.
  • -v/--verbose: increase logging (use -vv for debug-level traces about tool usage).
  • -q/--quiet: suppress logs (errors only).

Tools

Tools live under simple_agent/tools and implement a tiny interface (name, description, run). Two simple defaults ship with the CLI:

  • time: returns the current UTC timestamp.
  • calculator: evaluates small arithmetic expressions safely.
  • file_reader: dumps a snippet of a local text file (path[:start-end]).
  • python: runs a short Python snippet in a separate interpreter (default imports include math, json, os, sys, psutil, bs4; extend via PYTHON_TOOL_IMPORTS).

The python tool executes with a module allowlist. By default it includes: collections, datetime, functools, itertools, json, math, os, pathlib, psutil, random, statistics, sys, time, bs4. Set PYTHON_TOOL_IMPORTS (comma separated) to append additional modules if needed (e.g., requests).

Adding new tools only requires dropping a module next to the others and including it in load_default_tools().

Extending the agent

  • To add more model providers, create a new backend in simple_agent/backends that implements LLMBackend.
  • Swap in custom tools by editing load_default_tools() or wiring your own list in main.py.
  • For more complex automations, adjust the system prompt or max turn count to shape the agent's autonomy.