We're building a spec-to-code CLI that turns a plain-English function description into a Python module with matching pytest tests. It helps backend developers who want to stop writing boilerplate and keep test coverage consistent from the first commit.
What you'll need
- Python 3.10 or newer installed on your machine
- An Oxlo.ai API key from https://portal.oxlo.ai
- The OpenAI SDK:
pip install openai
Step 1: Verify the Oxlo.ai client with a smoke test
Before I wire up file I/O, I want to confirm the endpoint and model respond exactly like the OpenAI SDK expects. I use Llama 3.3 70B because it handles general-purpose coding tasks reliably.
from openai import OpenAI
client = OpenAI(base_url="https://api.oxlo.ai/v1", api_key="YOUR_OXLO_API_KEY")
response = client.chat.completions.create(
model="llama-3.3-70b",
messages=[
{"role": "system", "content": "You are a Python expert."},
{"role": "user", "content": "Write a Python function that validates an email address with a regex."},
],
)
print(response.choices[0].message.content)
Step 2: Define the system prompt for structured output
The agent needs to return two distinct code blocks every time: one for the implementation and one for the tests. I force that structure through a detailed system prompt.
SYSTEM_PROMPT = """You are a senior Python engineer. When given a function specification, output exactly two fenced Markdown code blocks in this order:
1. A Python file named implementation.py containing the implementation.
2. A Python file named test_implementation.py containing pytest tests.
After each code block, add a one-line comment starting with # Explanation: that describes the key design choices.
Rules:
- Use type hints.
- Handle edge cases explicitly.
- Do not write a main block or example usage.
- Tests must cover happy paths and at least two edge cases.
"""Step 3: Parse the response into separate files
I need a robust way to split the Markdown into code without getting confused by explanation text. A regex over triple backticks does the job.
import re
def extract_code_blocks(text: str) -> list[tuple[str, str]]:
"""
Returns a list of (filename_hint, code) tuples.
Looks for
```python ... ```
fences.
"""
pattern = r"
```python\s*(.*?)```
"
matches = re.findall(pattern, text, re.DOTALL)
files = []
for idx, code in enumerate(matches, start=1):
clean = code.strip()
if "test_" in clean[:50]:
filename = "test_implementation.py"
else:
filename = "implementation.py"
files.append((filename, clean))
return filesStep 4: Add a review loop to harden the code
Raw first drafts often miss input validation. I send the generated code back to the model with a review prompt, asking it to return only a corrected version. Because Oxlo.ai uses flat per-request pricing, adding this review step does not scale costs with prompt length. See https://oxlo.ai/pricing for plan details.
def review_code(spec: str, implementation: str) -> str:
review_prompt = (
f"Original spec:\n{spec}\n\n"
f"Current implementation:\n
```python\n{implementation}\n```
\n\n"
"Review this code for edge cases, type safety, and input validation. "
"Return only the corrected implementation inside a single
```python fence. "
"Do not change the function signature unless the spec requires it."
)
response = client.chat.completions.create(
model="qwen-3-32b",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": review_prompt},
],
)
blocks = extract_code_blocks(response.choices[0].message.content)
return blocks[0][1] if blocks else implementationStep 5: Generate tests from the spec and final code
I keep test generation separate so the tests validate behavior rather than parrot the implementation. I ask for pytest style with descriptive docstrings.
def generate_tests(spec: str, implementation: str) -> str:
test_prompt = (
f"Specification:\n{spec}\n\n"
f"Implementation:\n```
python\n{implementation}\n
```
\n\n"
"Write pytest unit tests for the implementation above. "
"Cover normal cases, boundary values, and error conditions. "
"Use descriptive test names and keep tests isolated."
)
response = client.chat.completions.create(
model="llama-3.3-70b",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": test_prompt},
],
)
blocks = extract_code_blocks(response.choices[0].message.content)
return blocks[0][1] if blocks else ""Step 6: Wrap the pipeline in a CLI
I pull everything together into a small script that reads a spec from a text file and writes the two Python files to disk.
import argparse
from pathlib import Path
def main() -> None:
parser = argparse.ArgumentParser(description="Spec-to-code generator")
parser.add_argument("spec_file", type=Path, help="Path to a .txt spec file")
parser.add_argument("--out-dir", type=Path, default=Path("."), help="Output directory")
args = parser.parse_args()
spec = args.spec_file.read_text()
# Initial generation
response = client.chat.completions.create(
model="llama-3.3-70b",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": spec},
],
)
blocks = extract_code_blocks(response.choices[0].message.content)
impl = next((code for fname, code in blocks if fname == "implementation.py"), "")
tests = next((code for fname, code in blocks if fname == "test_implementation.py"), "")
# Review loop
if impl:
impl = review_code(spec, impl)
# Regenerate tests against finalized implementation
if impl:
tests = generate_tests(spec, impl)
args.out_dir.mkdir(parents=True, exist_ok=True)
(args.out_dir / "implementation.py").write_text(impl)
(args.out_dir / "test_implementation.py").write_text(tests)
print(f"Wrote files to {args.out_dir.resolve()}")
if __name__ == "__main__":
main()Run it
Save the complete script as codegen.py, create a spec file, and invoke it.
spec.txt:
Write a function parse_iso_duration that takes an ISO 8601 duration string like "PT30M" or "P1Y2M10DT2H30M" and returns the total number of seconds as an integer. If the string is empty or malformed, raise ValueError.Command:
python codegen.py spec.txt --out-dir ./generatedConsole output:
Wrote files to /home/dev/project/generatedgenerated/implementation.py:
import re
def parse_iso_duration(duration: str) -> int:
"""Parse an ISO 8601 duration and return total seconds."""
if not isinstance(duration, str):
raise TypeError("duration must be a string")
if not duration:
raise ValueError("duration string is empty")
pattern = r'^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$'
match = re.match(pattern, duration)
if not match:
raise ValueError(f"malformed ISO 8601 duration: {duration}")
years, months, days, hours, minutes, seconds = (
int(g or 0) for g in match.groups()
)
total = (
years * 365 * 24 * 3600 +
months * 30 * 24 * 3600 +
days * 24 * 3600 +
hours * 3600 +
minutes * 60 +
seconds
)
return total
generated/test_implementation.py:
import pytest
from implementation import parse_iso_duration
def test_minutes_only():
assert parse_iso_duration("PT30M") == 1800
def test_full_duration():
expected = 1*365*24*3600 + 2*30*24*3600 + 10*24*3600 + 2*3600 + 30*60
assert parse_iso_duration("P1Y2M10DT2H30M") == expected
def test_empty_string_raises():
with pytest.raises(ValueError):
parse_iso_duration("")
def test_malformed_string_raises():
with pytest.raises(ValueError):
parse_iso_duration("30M")
def test_non_string_raises():
with pytest.raises(TypeError):
parse_iso_duration(None)
Wrap-up
This pipeline gives you a repeatable way to generate skeleton code and tests from nothing more than a sentence or two. Two concrete next steps: first, add a --model flag so you can swap between Llama 3.3 70B and DeepSeek V3.2 depending on whether you want speed or deeper reasoning. Second, wire the script into a pre-commit hook that auto-generates missing tests whenever it sees a new function docstring in your diff.
Top comments (0)