Python Agent

A local coding agent that uses Ollama with tool calling. It can read, write, and run Python files under ~/repo to complete a task you give it.

How it works

You give the agent a prompt and a directory under ~/repo to return code. It talks to a local Ollama model, which can ask this program to read files, write files, or run Python scripts. Results go back to the model so it can keep working until the goal is met (or it hits the turn limit).

flowchart TD
  you["You"] --> main["main.py"]
  main --> agent["Agent"]
  agent <--> ollama["Ollama model"]
  agent <--> tools["Local file tools<br/>read / write / run"]

Loading

Requirements

• Python 3.10+
• Ollama running locally
• A tool-capable model (default: llama3.1:8b)
• Python package: ollama

ollama serve
ollama pull llama3.1:8b
pip install ollama

Usage

Use plain single quotes in zsh/bash so special characters do not break the shell:

python main.py 'Create a hello.py script that prints Hello and run it to verify.'

Skip the directory prompt

python main.py --dir demos/hello 'Create hello.py that prints Hello.'

Default task

If you omit the task argument, the agent uses the built-in goal: create calculator.py that calculates factors, run it, and fix errors if standard output is empty.

Configuration

Edit config.py:

Setting	Purpose
MODEL_NAME	Ollama model tag (e.g. llama3.1:8b)
MAX_ITERATIONS	Safety cap on agent loop turns (default 15)
SYSTEM_PROMPT	Instructions for tool use and file writing

Project layout

File	Role
main.py	CLI entrypoint, work-dir prompt / --dir, starts the loop
agent.py	Chat loop, tool execution, fake tool-call handling
tools.py	Local tools and ~/repo path guards
config.py	Model, iteration limit, system prompt

Tools

Tool	Description
read_local_file	Read a file under ~/repo
write_local_file	Write a file (rejects empty content)
run_python_script	Run a Python file with python3 (10s timeout)

Relative paths resolve inside the chosen work directory. Absolute paths must stay under ~/repo. Paths like /repo/... are mapped to ~/repo/....

Ollama builds the tool schema from each function’s name, type hints, and docstring. Other LLM APIs usually need that schema specified explicitly instead of passing Python callables.

Example

cd ~/repo/python-agent
python main.py --dir demos/factors

Expected shape of output:

Work directory: /home/<you>/repo/demos/factors
Starting agent with goal: ...

[Iter 1] Executing Tool: write_local_file({...})
  -> Successfully wrote file to ... (N bytes)
[Iter 2] Executing Tool: run_python_script({...})
  -> STDOUT:
...

[Agent Completed Task]:
...