How curiousabhee/python-coding-agent works
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 main.py · get_file_content.py read file · call_function.py call_function.py · write_file.py write file
Components 22
Agent runtime
Orchestration and model loop
- main.py · Entry point that runs the coding-agent loop
main.py - prompts.py · Constrains agent behavior and tool usage
prompts.py - config.py · Loads environment-driven settings such as API keys
config.py - call_function.py · Routes LLM tool calls to concrete Python functions
call_function.py - Groq LLM · Function-calling model that drives the agent loop
Tool boundary
Filesystem and execution tools exposed to the LLM
- list files · Returns project file inventory for discovery
functions/get_files_info.py - read file · Reads source or test file contents for inspection
functions/get_file_content.py - write file · Writes patched file contents back to the repository
functions/write_file.py - run python · Executes Python files for verification and feedback
functions/run_python_file.py
Target app
Calculator project the agent edits and runs
- calc main · Calculator package entry point
calculator/main.py - calculator core · Primary calculator implementation
calculator/pkg/calculator.py - rendering · Formatting or output rendering for calculator results
calculator/pkg/render.py - calc tests · Tests for the calculator application itself
calculator/tests.py - sample data · Text fixtures used by the calculator project
calculator/lorem.txt - pkg data · Additional sample text data under the package
calculator/pkg/morelorem.txt
Repo infra
Configuration, packaging, and local execution support
- tool tests · Tests for file-discovery helper behavior
test/test_get_files_info.py - tool tests · Tests for file-read helper behavior
test/test_get_file_content.py - model tests · Tests for model and orchestration-related logic
test/test_models.py - tool tests · Tests for Python execution helper behavior
test/test_run_python_file.py - tool tests · Tests for file-write helper behavior
test/test_write_file.py - pyproject.toml · Project metadata and dependency definition
pyproject.toml - uv.lock · Pinned dependency resolution for reproducible runs
uv.lock
Connections 26
- 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