We are going to build a codebase architecture agent that ingests an entire project and answers cross-file questions. It helps teams onboard to legacy monoliths where retrieval alone misses implicit dependencies. Because Oxlo.ai charges a flat rate per request, we can pass in tens of thousands of tokens of source code without the bill scaling by the token.
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
Export your key as OXLO_API_KEY before running the script.
Step 1: Configure the Oxlo.ai client
I always start by proving the pipe works. This snippet points the OpenAI SDK at Oxlo.ai and asks Llama 3.3 70B for a one-word confirmation.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.oxlo.ai/v1",
api_key=os.environ["OXLO_API_KEY"],
)
response = client.chat.completions.create(
model="llama-3.3-70b",
messages=[{"role": "user", "content": "Reply with the single word: connected"}],
max_tokens=10,
)
print(response.choices[0].message.content)
Step 2: Generate a sample codebase
To keep the tutorial self-contained, we will create a toy project with three modules that share hidden dependencies. In practice you would point this at your own repo.
import os
PROJECT_DIR = "./sample_project"
files = {
"database.py": '''class ConnectionPool:
def __init__(self, max_size=10):
self.max_size = max_size
self._pool = []
def acquire(self):
if len(self._pool) < self.max_size:
self._pool.append("conn")
return self._pool[-1]
''',
"api.py": '''from database import ConnectionPool
class UserService:
def __init__(self):
# Implicit dependency: assumes ConnectionPool is already warmed up
self.db = ConnectionPool(max_size=20)
def get_user(self, user_id):
conn = self.db.acquire()
return {"id": user_id, "conn": conn}
''',
"main.py": '''from api import UserService
from database import ConnectionPool
if __name__ == "__main__":
pool = ConnectionPool(max_size=5)
service = UserService()
print(service.get_user(42))
''',
}
os.makedirs(PROJECT_DIR, exist_ok=True)
for name, content in files.items():
with open(os.path.join(PROJECT_DIR, name), "w") as f:
f.write(content.strip() + "\n")
print("Created", len(files), "files in", PROJECT_DIR)
Step 3: Assemble the context and system prompt
We read every file, wrap it in tags so the model knows where each file starts, and prepend a strict system prompt. Keeping the system prompt separate makes it easy to tweak behavior later.
SYSTEM_PROMPT = """You are a senior staff engineer.
Analyze the provided codebase and answer questions about it.
Be concise. When discussing dependencies, cite specific file names and line numbers if possible.
If you are unsure, say so."""
def assemble_context(directory):
chunks = []
for root, _, filenames in os.walk(directory):
for fname in sorted(filenames):
if not fname.endswith(".py"):
continue
path = os.path.join(root, fname)
with open(path, "r") as f:
content = f.read()
chunks.append(f"<file path='{path}'>\n{content}\n</file>")
return "\n\n".join(chunks)
context = assemble_context(PROJECT_DIR)
print(f"Context size: {len(context)} characters")
Step 4: Send the long context to Oxlo.ai
Now we ship the entire payload. I use Kimi K2.6 because its 131K context window easily holds large codebases, and on Oxlo.ai the cost is still one flat request. We stream the response so we can watch it arrive.
question = (
"Identify the hidden dependency bug between ConnectionPool and UserService. "
"Explain which file violates the pool size constraint and why."
)
response = client.chat.completions.create(
model="kimi-k2.6",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": f"{context}\n\nQuestion: {question}"},
],
stream=True,
)
for chunk in response:
print(chunk.choices[0].delta.content or "", end="")
print()
If you need stronger reasoning, swap the model to deepseek-v3.2 or qwen-3-32b. Both are available on Oxlo.ai with the same request-based pricing.
Run it
Here is the complete script. Save it as codebase_agent.py, run python codebase_agent.py, and it will create the sample project, load the context, and query the model.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.oxlo.ai/v1",
api_key=os.environ["OXLO_API_KEY"],
)
SYSTEM_PROMPT = """You are a senior staff engineer.
Analyze the provided codebase and answer questions about it.
Be concise. When discussing dependencies, cite specific file names and line numbers if possible.
If you are unsure, say so."""
PROJECT_DIR = "./sample_project"
def build_sample_project():
files = {
"database.py": '''class ConnectionPool:
def __init__(self, max_size=10):
self.max_size = max_size
self._pool = []
def acquire(self):
if len(self._pool) < self.max_size:
self._pool.append("conn")
return self._pool[-1]
''',
"api.py": '''from database import ConnectionPool
class UserService:
def __init__(self):
self.db = ConnectionPool(max_size=20)
def get_user(self, user_id):
conn = self.db.acquire()
return {"id": user_id, "conn": conn}
''',
"main.py": '''from api import UserService
from database import ConnectionPool
if __name__ == "__main__":
pool = ConnectionPool(max_size=5)
service = UserService()
print(service.get_user(42))
''',
}
os.makedirs(PROJECT_DIR, exist_ok=True)
for name, content in files.items():
with open(os.path.join(PROJECT_DIR, name), "w") as f:
f.write(content.strip() + "\n")
def assemble_context(directory):
chunks = []
for root, _, filenames in os.walk(directory):
for fname in sorted(filenames):
if not fname.endswith(".py"):
continue
path = os.path.join(root, fname)
with open(path, "r") as f:
content = f.read()
chunks.append(f"<file path='{path}'>\n{content}\n</file>")
return "\n\n".join(chunks)
def main():
build_sample_project()
context = assemble_context(PROJECT_DIR)
print(f"Loaded context: {len(context)} chars\n")
question = (
"Identify the hidden dependency bug between ConnectionPool and UserService. "
"Explain which file violates the pool size constraint and why."
)
response = client.chat.completions.create(
model="kimi-k2.6",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": f"{context}\n\nQuestion: {question}"},
],
stream=True,
)
print("Answer:")
for chunk in response:
print(chunk.choices[0].delta.content or "", end="")
print()
if __name__ == "__main__":
main()
Example output:
Loaded context: 847 chars
Answer:
The hidden dependency bug is in api.py. UserService instantiates its own ConnectionPool with max_size=20 inside __init__, ignoring any pool created elsewhere. Meanwhile main.py creates a separate pool with max_size=5 but never passes it to UserService. The two pools are isolated, so the global limit intended by main.py is bypassed. To fix it, inject the pool via the constructor rather than hard-coding a new instance.
Wrap-up
You now have a working agent that can swallow an entire project and reason across files. Two concrete next steps: wire this into a Git pre-commit hook to catch architectural regressions before they reach review, or extend the assembler to include .md docs and use deepseek-v3.2 for deeper reasoning on complex code. For pricing details on running this at scale, see https://oxlo.ai/pricing.
Top comments (0)