# curiousabhee/python-coding-agent architecture

> Architecture diagram of the GitHub repository curiousabhee/python-coding-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/curiousabhee/python-coding-agent
- Repository: https://github.com/curiousabhee/python-coding-agent

## Overview

1. **What this repo is**
   - This is a **Python coding agent** that uses an LLM to inspect, modify, and test a separate Python project in the same repository: the `calculator/` package.

2. **Top-level runtime flow**
   - A user runs `main.py` with a natural-language task such as “Fix the calculator bug”.
   - The agent sends that task, plus a system prompt, to Groq’s LLM.
   - The LLM can request tools; the agent executes them and feeds the results back into the model in a loop.
   - The loop repeats up to 20 iterations or until the model stops requesting tools.

3. **Agent control plane**
   - `main.py` is the orchestration entry point.
   - `prompts.py` contains the system prompt that constrains the agent’s behavior.
   - `config.py` holds runtime configuration, including environment-based settings like the Groq API key.
   - `call_function.py` is the dispatcher that maps model tool calls to concrete Python functions.

4. **Tool layer boundary**
   - The `functions/` directory is the agent’s tool API.
   - It exposes four actions:
     - list project files
     - read file contents
     - write file contents
     - run a Python file
   - These tools are the only way the model interacts with the repository filesystem and test execution.

5. **Filesystem inspection path**
   - `functions/get_files_info.py` and `functions/get_file_content.py` provide read access to the codebase.
   - This is how the agent discovers structure, inspects source files, and reads test files before making changes.

6. **Modification path**
   - `functions/write_file.py` is the write boundary.
   - The agent uses it to patch source files inside the target project, rather than editing files directly in-process.

7. **Execution and verification path**
   - `functions/run_python_file.py` runs Python files, which is the agent’s primary feedback loop for validating fixes.
   - This is likely used to execute tests or run the target application logic after edits.

8. **Target application being fixed**
   - `calculator/` is the code under repair, not the agent itself.
   - It contains `calculator/main.py`, `calculator/pkg/calculator.py`, and `calculator/pkg/render.py`, indicating a small package with a main entry point and supporting library code.
   - The text files in `calculator/` and `calculator/pkg/` suggest sample inputs/fixtures used by the calculator project.

9. **Testing split**
   - The repo has its own tool tests under `test/`, covering the agent’s helper functions and models.
   - The `calculator/tests.py` file belongs to the target calculator project and is likely what the agent reads/runs to diagnose bugs.
   - This creates two test boundaries: one for the agent infrastructure, one for the project it fixes.

10. **External dependency boundary**
    - The LLM backend is **Groq**, specifically a function-calling model (`llama-3.3-70b-versatile` per README).
    - The repo depends on environment configuration via `.env` / `.env.example` for `GROQ_API_KEY`.

11. **Packaging and execution model**
    - The project uses `uv` for dependency management and execution (`uv sync`, `uv run main.py ...`).
    - `pyproject.toml` and `uv.lock` define the Python environment and reproducible dependencies.

12. **Architectural summary**
    - Overall, this repo is a **tool-using agent shell** wrapped around a **separate calculator codebase**.
    - The key diagram should show:
      - user input → agent orchestrator → Groq LLM
      - LLM ↔ tool dispatcher ↔ filesystem/test execution
      - tools operating on the `calculator/` project
      - results feeding back into the LLM until a final answer is produced

Main entry points: [`main.py`](https://github.com/curiousabhee/python-coding-agent/blob/main/main.py) (main.py), [`functions/get_file_content.py`](https://github.com/curiousabhee/python-coding-agent/blob/main/functions/get_file_content.py) (read file), [`call_function.py`](https://github.com/curiousabhee/python-coding-agent/blob/main/call_function.py) (call_function.py), [`functions/write_file.py`](https://github.com/curiousabhee/python-coding-agent/blob/main/functions/write_file.py) (write file)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent runtime"]
  node_main_py["main.py<br/>orchestrator<br/>[main.py]"]
  node_prompts_py["prompts.py<br/>system prompt<br/>[prompts.py]"]
  node_config_py["config.py<br/>runtime config<br/>[config.py]"]
  node_call_function_py["call_function.py<br/>tool dispatcher<br/>[call_function.py]"]
  node_groq_api(("Groq LLM<br/>external model"))
end

subgraph group_tools["Tool boundary"]
  node_get_files_info_py["list files<br/>read tool<br/>[get_files_info.py]"]
  node_get_file_content_py["read file<br/>read tool"]
  node_write_file_py["write file<br/>write tool<br/>[write_file.py]"]
  node_run_python_file_py["run python<br/>exec tool<br/>[run_python_file.py]"]
end

subgraph group_target["Target app"]
  node_calc_main_py["calc main<br/>app entry<br/>[main.py]"]
  node_calculator_py["calculator core<br/>domain logic<br/>[calculator.py]"]
  node_render_py["rendering<br/>presentation<br/>[render.py]"]
  node_calc_tests_py["calc tests<br/>project tests<br/>[tests.py]"]
  node_calc_data_root["sample data<br/>fixture files<br/>[lorem.txt]"]
  node_calc_data_pkg["pkg data<br/>fixture files<br/>[morelorem.txt]"]
end

subgraph group_infra["Repo infra"]
  node_test_get_files_info_py["tool tests<br/>agent tests"]
  node_test_get_file_content_py["tool tests<br/>agent tests"]
  node_test_models_py["model tests<br/>agent tests<br/>[test_models.py]"]
  node_test_run_python_file_py["tool tests<br/>agent tests"]
  node_test_write_file_py["tool tests<br/>agent tests<br/>[test_write_file.py]"]
  node_pyproject_toml["pyproject.toml<br/>packaging<br/>[pyproject.toml]"]
  node_uv_lock["uv.lock<br/>lockfile<br/>[uv.lock]"]
end

node_main_py -->|"loads prompt"| node_prompts_py
node_main_py -->|"reads config"| node_config_py
node_main_py -->|"calls model"| node_groq_api
node_groq_api -->|"requests tools"| node_call_function_py
node_call_function_py -->|"dispatch"| node_get_files_info_py
node_call_function_py -->|"dispatch"| node_get_file_content_py
node_call_function_py -->|"dispatch"| node_write_file_py
node_call_function_py -->|"dispatch"| node_run_python_file_py
node_get_files_info_py -->|"inspects"| node_calc_main_py
node_get_file_content_py -->|"reads"| node_calculator_py
node_get_file_content_py -->|"reads"| node_render_py
node_get_file_content_py -->|"reads"| node_calc_tests_py
node_get_file_content_py -->|"reads"| node_calc_data_root
node_get_file_content_py -->|"reads"| node_calc_data_pkg
node_write_file_py -->|"modifies"| node_calculator_py
node_write_file_py -->|"modifies"| node_render_py
node_run_python_file_py -->|"executes"| node_calc_main_py
node_run_python_file_py -->|"executes"| node_calc_tests_py
node_main_py -->|"loops"| node_call_function_py
node_main_py -->|"supported by"| node_test_models_py
node_main_py -->|"supported by"| node_test_get_files_info_py
node_main_py -->|"supported by"| node_test_get_file_content_py
node_main_py -->|"supported by"| node_test_run_python_file_py
node_main_py -->|"supported by"| node_test_write_file_py
node_config_py -->|"configured by"| node_pyproject_toml
node_pyproject_toml -->|"pins"| node_uv_lock

click node_main_py "https://github.com/curiousabhee/python-coding-agent/blob/main/main.py"
click node_prompts_py "https://github.com/curiousabhee/python-coding-agent/blob/main/prompts.py"
click node_config_py "https://github.com/curiousabhee/python-coding-agent/blob/main/config.py"
click node_call_function_py "https://github.com/curiousabhee/python-coding-agent/blob/main/call_function.py"
click node_get_files_info_py "https://github.com/curiousabhee/python-coding-agent/blob/main/functions/get_files_info.py"
click node_get_file_content_py "https://github.com/curiousabhee/python-coding-agent/blob/main/functions/get_file_content.py"
click node_write_file_py "https://github.com/curiousabhee/python-coding-agent/blob/main/functions/write_file.py"
click node_run_python_file_py "https://github.com/curiousabhee/python-coding-agent/blob/main/functions/run_python_file.py"
click node_calc_main_py "https://github.com/curiousabhee/python-coding-agent/blob/main/calculator/main.py"
click node_calculator_py "https://github.com/curiousabhee/python-coding-agent/blob/main/calculator/pkg/calculator.py"
click node_render_py "https://github.com/curiousabhee/python-coding-agent/blob/main/calculator/pkg/render.py"
click node_calc_tests_py "https://github.com/curiousabhee/python-coding-agent/blob/main/calculator/tests.py"
click node_calc_data_root "https://github.com/curiousabhee/python-coding-agent/blob/main/calculator/lorem.txt"
click node_calc_data_pkg "https://github.com/curiousabhee/python-coding-agent/blob/main/calculator/pkg/morelorem.txt"
click node_test_get_files_info_py "https://github.com/curiousabhee/python-coding-agent/blob/main/test/test_get_files_info.py"
click node_test_get_file_content_py "https://github.com/curiousabhee/python-coding-agent/blob/main/test/test_get_file_content.py"
click node_test_models_py "https://github.com/curiousabhee/python-coding-agent/blob/main/test/test_models.py"
click node_test_run_python_file_py "https://github.com/curiousabhee/python-coding-agent/blob/main/test/test_run_python_file.py"
click node_test_write_file_py "https://github.com/curiousabhee/python-coding-agent/blob/main/test/test_write_file.py"
click node_pyproject_toml "https://github.com/curiousabhee/python-coding-agent/blob/main/pyproject.toml"
click node_uv_lock "https://github.com/curiousabhee/python-coding-agent/blob/main/uv.lock"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_py,node_prompts_py,node_config_py,node_call_function_py,node_groq_api toneBlue
class node_get_files_info_py,node_get_file_content_py,node_write_file_py,node_run_python_file_py toneAmber
class node_calc_main_py,node_calculator_py,node_render_py,node_calc_tests_py,node_calc_data_root,node_calc_data_pkg toneMint
class node_test_get_files_info_py,node_test_get_file_content_py,node_test_models_py,node_test_run_python_file_py,node_test_write_file_py,node_pyproject_toml,node_uv_lock toneRose
```

## Components

### Agent runtime

Orchestration and model loop

- [main.py](https://github.com/curiousabhee/python-coding-agent/blob/main/main.py): orchestrator · Entry point that runs the coding-agent loop · `main.py`
- [prompts.py](https://github.com/curiousabhee/python-coding-agent/blob/main/prompts.py): system prompt · Constrains agent behavior and tool usage · `prompts.py`
- [config.py](https://github.com/curiousabhee/python-coding-agent/blob/main/config.py): runtime config · Loads environment-driven settings such as API keys · `config.py`
- [call_function.py](https://github.com/curiousabhee/python-coding-agent/blob/main/call_function.py): tool dispatcher · Routes LLM tool calls to concrete Python functions · `call_function.py`
- **Groq LLM**: external model · Function-calling model that drives the agent loop

### Tool boundary

Filesystem and execution tools exposed to the LLM

- [list files](https://github.com/curiousabhee/python-coding-agent/blob/main/functions/get_files_info.py): read tool · Returns project file inventory for discovery · `functions/get_files_info.py`
- [read file](https://github.com/curiousabhee/python-coding-agent/blob/main/functions/get_file_content.py): read tool · Reads source or test file contents for inspection · `functions/get_file_content.py`
- [write file](https://github.com/curiousabhee/python-coding-agent/blob/main/functions/write_file.py): write tool · Writes patched file contents back to the repository · `functions/write_file.py`
- [run python](https://github.com/curiousabhee/python-coding-agent/blob/main/functions/run_python_file.py): exec tool · Executes Python files for verification and feedback · `functions/run_python_file.py`

### Target app

Calculator project the agent edits and runs

- [calc main](https://github.com/curiousabhee/python-coding-agent/blob/main/calculator/main.py): app entry · Calculator package entry point · `calculator/main.py`
- [calculator core](https://github.com/curiousabhee/python-coding-agent/blob/main/calculator/pkg/calculator.py): domain logic · Primary calculator implementation · `calculator/pkg/calculator.py`
- [rendering](https://github.com/curiousabhee/python-coding-agent/blob/main/calculator/pkg/render.py): presentation · Formatting or output rendering for calculator results · `calculator/pkg/render.py`
- [calc tests](https://github.com/curiousabhee/python-coding-agent/blob/main/calculator/tests.py): project tests · Tests for the calculator application itself · `calculator/tests.py`
- [sample data](https://github.com/curiousabhee/python-coding-agent/blob/main/calculator/lorem.txt): fixture files · Text fixtures used by the calculator project · `calculator/lorem.txt`
- [pkg data](https://github.com/curiousabhee/python-coding-agent/blob/main/calculator/pkg/morelorem.txt): fixture files · Additional sample text data under the package · `calculator/pkg/morelorem.txt`

### Repo infra

Configuration, packaging, and local execution support

- [tool tests](https://github.com/curiousabhee/python-coding-agent/blob/main/test/test_get_files_info.py): agent tests · Tests for file-discovery helper behavior · `test/test_get_files_info.py`
- [tool tests](https://github.com/curiousabhee/python-coding-agent/blob/main/test/test_get_file_content.py): agent tests · Tests for file-read helper behavior · `test/test_get_file_content.py`
- [model tests](https://github.com/curiousabhee/python-coding-agent/blob/main/test/test_models.py): agent tests · Tests for model and orchestration-related logic · `test/test_models.py`
- [tool tests](https://github.com/curiousabhee/python-coding-agent/blob/main/test/test_run_python_file.py): agent tests · Tests for Python execution helper behavior · `test/test_run_python_file.py`
- [tool tests](https://github.com/curiousabhee/python-coding-agent/blob/main/test/test_write_file.py): agent tests · Tests for file-write helper behavior · `test/test_write_file.py`
- [pyproject.toml](https://github.com/curiousabhee/python-coding-agent/blob/main/pyproject.toml): packaging · Project metadata and dependency definition · `pyproject.toml`
- [uv.lock](https://github.com/curiousabhee/python-coding-agent/blob/main/uv.lock): lockfile · Pinned dependency resolution for reproducible runs · `uv.lock`

## Connections

- main.py → prompts.py: loads prompt · Main orchestrator injects the system prompt
- main.py → config.py: reads config · Main loads runtime settings and credentials
- main.py → Groq LLM: calls model · Sends task and conversation state to Groq
- Groq LLM → call_function.py: requests tools · Model emits function calls that are dispatched locally
- call_function.py → list files: dispatch · Executes file listing tool
- call_function.py → read file: dispatch · Executes file read tool
- call_function.py → write file: dispatch · Executes file write tool
- call_function.py → run python: dispatch · Executes Python run tool
- list files → calc main: inspects · Discovers target project structure
- read file → calculator core: reads · Inspects implementation files
- read file → rendering: reads · Inspects implementation files
- read file → calc tests: reads · Reads target project tests while diagnosing bugs
- read file → sample data: reads · Reads sample data used by the calculator app
- read file → pkg data: reads · Reads sample data used by the calculator app
- write file → calculator core: modifies · Patches calculator implementation files
- write file → rendering: modifies · Patches calculator presentation code
- run python → calc main: executes · Runs calculator entry point or related scripts
- run python → calc tests: executes · Runs calculator tests for validation
- main.py → call_function.py: loops · Feeds tool results back into the conversation until done
- main.py → model tests: supported by · Repo tests cover agent-side model logic
- main.py → tool tests: supported by · Repo tests cover file-discovery tool
- main.py → tool tests: supported by · Repo tests cover file-read tool
- main.py → tool tests: supported by · Repo tests cover execution tool
- main.py → tool tests: supported by · Repo tests cover file-write tool
- config.py → pyproject.toml: configured by · Dependency and runtime metadata are defined in project config
- pyproject.toml → uv.lock: pins · Lockfile captures resolved environment
