We are building a spec-to-service agent that reads a plain-text API requirement and outputs a deployable FastAPI microservice with tests, a Dockerfile, and a docker-compose file. This gives backend teams a reproducible starting point for new internal services and cuts repetitive boilerplate to near zero. Because the pipeline runs multiple LLM passes, Oxlo.ai's per-request pricing keeps costs flat even when context grows; see https://oxlo.ai/pricing for details.
What you'll need
- Python 3.10 or newer
- The OpenAI SDK:
pip install openai - An Oxlo.ai API key from https://portal.oxlo.ai
- Docker if you want to run the final container locally
Step 1: Scaffold the project
Create a working directory and initialize the Oxlo.ai client. I keep the API key in an environment variable so it never hits disk in plaintext.
import os
import re
import json
from openai import OpenAI
client = OpenAI(
base_url="https://api.oxlo.ai/v1",
api_key=os.getenv("OXLO_API_KEY")
)
OUTPUT_DIR = "./generated_service"
os.makedirs(OUTPUT_DIR, exist_ok=True)Step 2: Parse the spec
The agent accepts a short JSON spec describing endpoints and data models. We validate the shape, then render it into a structured prompt so the model has clear constraints.
SPEC = {
"service_name": "inventory_api",
"endpoints": [
{"path": "/items", "method": "GET", "response_model": "ItemList"},
{"path": "/items", "method": "POST", "request_model": "ItemCreate", "response_model": "Item"}
],
"models": {
"Item": {"id": "int", "name": "str", "quantity": "int"},
"ItemCreate": {"name": "str", "quantity": "int"},
"ItemList": {"items": "List[Item]"}
}
}
def build_generation_prompt(spec: dict) -> str:
return f"""You are a senior backend engineer.
Write a production-ready FastAPI service based on the following specification.
Use pydantic models, type hints, and in-memory storage (a global dict).
Output ONLY the raw file contents, one file per code block labeled with its path.
Specification:
{json.dumps(spec, indent=2)}
Required files:
- main.py
- models.py
- requirements.txt
"""Step 3: Generate the service
I use DeepSeek V3.2 because it handles code generation and reasoning cleanly. The system prompt locks the output format to labeled code blocks so we can parse files automatically.
SYSTEM_PROMPT = """You are a senior Python engineer generating deployable backend services.
Rules:
1. Use FastAPI and Pydantic v2.
2. Include type hints on every function and model field.
3. Return raw file contents inside markdown code blocks with the format: ### filename.ext
```python
# code here
```
4. Do not include explanations outside the code blocks.
5. Use only in-memory storage. No external databases."""user_message = build_generation_prompt(SPEC)
response = client.chat.completions.create(
model="deepseek-v3.2",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": user_message},
],
temperature=0.2,
)
generated_text = response.choices[0].message.content
print(generated_text)Step 4: Parse and write artifacts
The model returns multiple files in one response. A small parser extracts each labeled block and writes it to the output directory. This keeps the pipeline fully automated.
def extract_files(text: str) -> dict:
pattern = r"###\s*(?P<filename>[\w./]+)\n
```python\n(?P<code>.*?)```
"
matches = re.finditer(pattern, text, re.DOTALL)
return {m.group("filename"): m.group("code").strip() for m in matches}
files = extract_files(generated_text)
for filename, content in files.items():
path = os.path.join(OUTPUT_DIR, filename)
os.makedirs(os.path.dirname(path), exist_ok=True)
with open(path, "w") as f:
f.write(content)
print(f"Wrote {path}")Step 5: Generate tests
I call the model again, this time feeding the generated main.py and models.py as context. Using Qwen 3 32B works well for agentic follow-up tasks. The goal is pytest coverage for the two endpoints.
def read_file(path: str) -> str:
with open(os.path.join(OUTPUT_DIR, path)) as f:
return f.read()
test_prompt = f"""Given the following FastAPI service files, write pytest tests in a single file named test_main.py.
Use TestClient from fastapi.testclient. Cover success cases and validation errors.
main.py:
{read_file('main.py')}
models.py:
{read_file('models.py')}
"""
response = client.chat.completions.create(
model="qwen-3-32b",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": test_prompt},
],
temperature=0.2,
)
test_text = response.choices[0].message.content
test_files = extract_files(test_text)
for filename, content in test_files.items():
path = os.path.join(OUTPUT_DIR, filename)
with open(path, "w") as f:
f.write(content)
print(f"Wrote {path}")Step 6: Self-review
Before declaring the service ready, I run a review pass with Kimi K2.6 to catch logic errors or missing imports. The model reads the combined files and returns a concise bug list. If it finds issues, feed them back into a fix pass. For this tutorial we log the review and apply any needed patches manually.
review_prompt = f"""Review the following service for bugs, missing imports, or type errors.
Return a numbered list of issues. If no issues, say "No issues found."
main.py:
{read_file('main.py')}
models.py:
{read_file('models.py')}
test_main.py:
{read_file('test_main.py')}
"""
response = client.chat.completions.create(
model="kimi-k2.6",
messages=[
{"role": "system", "content": "You are a strict code reviewer. Be concise."},
{"role": "user", "content": review_prompt},
],
temperature=0.1,
)
review = response.choices[0].message.content
print("Review output:\n", review)
with open(os.path.join(OUTPUT_DIR, "review.txt"), "w") as f:
f.write(review)Step 7: Package for deployment
The final step generates a Dockerfile and docker-compose.yml so the service is deployable immediately. I use Llama 3.3 70B for this general-purpose scaffolding task.
package_prompt = f"""Generate a Dockerfile and docker-compose.yml for a Python 3.11 FastAPI service.
The service listens on port 8000. Use uvicorn.
Place the files in the root. Output in the same labeled code block format.
Current requirements.txt:
{read_file('requirements.txt')}
"""
response = client.chat.completions.create(
model="llama-3.3-70b",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": package_prompt},
],
temperature=0.2,
)
package_text = response.choices[0].message.content
package_files = extract_files(package_text)
for filename, content in package_files.items():
path = os.path.join(OUTPUT_DIR, filename)
with open(path, "w") as f:
f.write(content)
print(f"Wrote {path}")Run it
Copy the snippets above into a single file named deploy_agent.py, then run it. The driver below ties every step together so the script is fully self-contained.
if __name__ == "__main__":
print("Starting spec-to-service pipeline...")
# Generate service
user_message = build_generation_prompt(SPEC)
response = client.chat.completions.create(
model="deepseek-v3.2",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": user_message},
],
temperature=0.2,
)
generated_text = response.choices[0].message.content
for filename, content in extract_files(generated_text).items():
path = os.path.join(OUTPUT_DIR, filename)
os.makedirs(os.path.dirname(path), exist_ok=True)
with open(path, "w") as f:
f.write(content)
print(f"Wrote {path}")
# Generate tests
test_prompt = f"""Given the following FastAPI service files, write pytest tests in a single file named test_main.py.
Use TestClient from fastapi.testclient. Cover success cases and validation errors.
main.py:
{read_file('main.py')}
models.py:
{read_file('models.py')}
"""
response = client.chat.completions.create(
model="qwen-3-32b",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": test_prompt},
],
temperature=0.2,
)
for filename, content in extract_files(response.choices[0].message.content).items():
with open(os.path.join(OUTPUT_DIR, filename), "w") as f:
f.write(content)
print(f"Wrote {filename}")
# Review
review_prompt = f"""Review the following service for bugs, missing imports, or type errors.
Return a numbered list of issues. If no issues, say "No issues found."
main.py:
{read_file('main.py')}
models.py:
{read_file('models.py')}
test_main.py:
{read_file('test_main.py')}
"""
response = client.chat.completions.create(
model="kimi-k2.6",
messages=[
{"role": "system", "content": "You are a strict code reviewer. Be concise."},
{"role": "user", "content": review_prompt},
],
temperature=0.1,
)
review = response.choices[0].message.content
print("Review output:\n", review)
with open(os.path.join(OUTPUT_DIR, "review.txt"), "w") as f:
f.write(review)
# Package
package_prompt = f"""Generate a Dockerfile and docker-compose.yml for a Python 3.11 FastAPI service.
The service listens on port 8000. Use uvicorn.
Place the files in the root. Output in the same labeled code block format.
Current requirements.txt:
{read_file('requirements.txt')}
"""
response = client.chat.completions.create(
model="llama-3.3-70b",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": package_prompt},
],
temperature=0.2,
)
for filename, content in extract_files(response.choices[0].message.content).items():
with open(os.path.join(OUTPUT_DIR, filename), "w") as f:
f.write(content)
print(f"Wrote {filename}")
print("\nPipeline complete. Run 'docker compose up' inside generated_service/ to deploy.")Example output:
Starting spec-to-service pipeline...
Wrote ./generated_service/main.py
Wrote ./generated_service/models.py
Wrote ./generated_service/requirements.txt
Wrote ./generated_service/test_main.py
Wrote ./generated_service/review.txt
Wrote ./generated_service/Dockerfile
Wrote ./generated_service/docker-compose.yml
Review output:
1. Add __init__.py if you plan to import the folder as a package.
2. No logic issues found.
Pipeline complete. Run 'docker compose up' inside generated_service/ to deploy.Wrap-up
Wire the generator into a CI pipeline so every new service spec opens a pull request with the scaffolded code automatically. You can also expand the self-review loop into an autonomous fix pass by feeding the review text back to DeepSeek V3.2 on Oxlo.ai and applying the suggested patches before the Docker build step.
Top comments (0)