When we first started building what would become Datapizza AI, our open-source GenAI framework, we had a simple but ambitious goal: to create a modular, elegant system that could adapt to any AI workflow.
We wanted it to be universal — a framework so well-designed that you could plug in any model, any retriever, any agent, and it would "just work."
It looked perfect on paper.
And that's exactly where it broke.
The Problem: Fighting Abstraction Layers
In 2024, when we formed our GenAI R&D team, we started by studying the existing frameworks. We were building production-grade RAG and AI Agent solutions, but we kept running into the same issues:
- Heavy abstraction layers imposed top-down
- Unnecessary complexity for our actual needs
- Black-box solutions that were impossible to debug
- Rigid architectures that didn't match real-world use cases
What We Actually Needed
What we needed were LEGO-like building blocks to compose our solutions flexibly, based on what empirically worked in production.
So we began building Datapizza AI with a clear philosophy:
- Thin abstraction layer just above provider libraries
- Highly modular and customizable components
- Observable at every step of execution
- No magic - just readable, composable code
Datapizza AI is not a magic wand with black-box solutions.
AI Engineers should keep tinkering and experimenting to deeply understand this technology. Instead, it's the toolbox for building complex use cases while keeping full control — without losing your mind over the code.
When Abstraction Becomes the Enemy
Our first prototype was a masterpiece of abstraction. Every part of the system — agents, pipelines, retrievers — was wrapped in big interfaces and generic classes. It felt powerful, even beautiful.
Then we started using it in real projects.
The Pain Points We Discovered
- Debugging nightmare: A single bug could send us digging through layers of indirection
- Fragile refactoring: A small change meant breaking three modules at once
- False decoupling: Adding features required touching "decoupled" code
- Lost understanding: We couldn't reason about our own system
The hard truth: Abstraction hides complexity — but it also hides understanding. When you can't reason about your own system, you can't trust it.
So we did something radical: we tore it all down.
The Rebuild: Clarity Over Cleverness
We stripped away abstractions until only what mattered remained. Every component became explicit and inspectable. The goal wasn't elegance anymore — it was clarity.
What This Looks Like in Practice
Here's how simple and explicit Datapizza AI agents are:
from datapizza.agents import Agent
from datapizza.clients.openai import OpenAIClient
from datapizza.tools import tool
@tool
def get_weather(city: str) -> str:
return f"The weather in {city} is sunny"
client = OpenAIClient(
api_key=os.getenv("OPENAI_API_KEY"),
model="gpt-4.1-mini"
)
agent = Agent(name="weather_agent", client=client, tools=[get_weather])
response = agent.run(task_input="what is the weather in rome?")
print(response.text)
Built-in Observability: Tracing That Actually Helps
A key requirement for principled development of LLM applications over your data (RAG systems, agents) is being able to observe and debug. Most frameworks treat this as an afterthought, but we built observability into Datapizza AI from day one.
Why Tracing Matters for AI Applications
When your agent makes 5 LLM calls, searches through 3 different databases, and processes 10 documents, you need to know:
- What was the actual flow of data?
- Which step is the bottleneck?
- How many tokens did each model consume?
- Where did the execution fail?
Detailed Tracing in Action
Datapizza AI provides built-in observability with OpenTelemetry tracing to help you monitor performance and understand execution flow:
from datapizza.clients.openai import OpenAIClient
from datapizza.tracing import ContextTracing
client = OpenAIClient(api_key="OPENAI_API_KEY", model="gpt-4.1-mini")
with ContextTracing().trace("my_ai_operation"):
response = client.invoke("hi, how are u?")
# Output shows:
# ╭─ Trace Summary of my_ai_operation ──────────────────────────────────╮
# │ Total Spans: 3 │
# │ Duration: 2.45s │
# │ ┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓ │
# │ ┃ Model ┃ Prompt Tokens ┃ Completion Tokens ┃ Cached Tokens ┃ │
# │ ┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩ │
# │ │ gpt-4o-mini │ 31 │ 27 │ 0 │ │
# │ └─────────────┴───────────────┴───────────────────┴───────────────┘ │
# ╰─────────────────────────────────────────────────────────────────────╯
What Makes This Different
Traditional approach: Add logging as an afterthought, dig through log files when something breaks.
Datapizza AI approach: Built-in tracing that shows you exactly what happened, when it happened, and how much it cost — without any additional setup.
This isn't just about debugging. It's about understanding your AI system so you can optimize performance, control costs, and build reliable applications.
Key Lessons from the Rebuild
Clarity beats cleverness - Every line of open-source code will be read, copied, and modified by someone else. If you have to explain how it works, it's already too complicated.
Documentation is part of the product - The best feature in the world is useless if no one understands how to use it. A clear README is worth a hundred Slack messages.
Less is often more - Every new feature adds cognitive load and potential fragility. Learning to say "no" — even to good ideas — is the essence of sustainable design.
Ship, learn, repeat - Perfection is a moving target. Every release is just another iteration of understanding your own system better.
From Code Reuse to Knowledge Reuse
When we started scaling our AI work, we noticed that the real challenge wasn't just reusing code — it was reusing knowledge. Each engineer was learning things about RAG, evaluation, or multi-agent workflows that lived in isolated notebooks.
Datapizza AI became a way to capture those insights — to make discovery itself modular. Every time we found a better ranking strategy or evaluation method, we'd ask: "Is this just an experiment, or should this become part of the framework?"
Features like observability via OpenTelemetry, vendor-agnostic model support, and multi-agent orchestration evolved naturally. Not as abstract ideas — but as reusable knowledge, encoded in code.
Where We Are Now
Today, Datapizza AI is open source — stable, readable, and used in production systems.
Current Features
- Multi-vendor support: OpenAI, Google, Anthropic, Mistral, and others
- Native observability: Built-in OpenTelemetry integration
- Multi-agent collaboration: Without unnecessary complexity
- Production-ready: Actually used in real systems
It's not perfect — and that's the point.
Software isn't about chasing perfection; it's about building systems that can evolve.
The Core Philosophy
If there's one lesson we'd share, it's this:
Engineering is restraint in disguise.
Every abstraction is a tradeoff between power and clarity. The sooner you learn which one matters more to you, the better your software becomes.
We built Datapizza AI to embody that principle — not as a product, but as a philosophy of building things you can actually understand.
Why Open Source?
We believe there's extraordinary technical talent in Italy that too often goes underappreciated. At Datapizza, we're trying to create a reference environment where this talent can emerge, grow, and have real impact.
Open-sourcing Datapizza AI is our chance to build, together with our community, proof that Italy is not sitting on the sidelines in GenAI.
Get Involved
If you're curious about our approach:
Explore Datapizza AI on GitHub
And if you've fought the same battles — abstraction, complexity, refactoring fatigue — we'd love to hear your story.
– The Datapizza Labs Team
Top comments (1)
wow