Since you're framing this as a learning resource, here are a couple things I see:
Your views are not following a single convention: some of them return dictionaries, some return base JSONResponse objects, and others return properly defined Pydantic schemas. I didn't run the code, but I'd venture to guess your generated documentation is not comprehensive, nor is it cohesive.
I'd also further extend this into your agent services; passing bare dictionaries with arbitrary fields into what is supposed to be a modular logic handler is pretty outdated. You're defining a functional (methods) interface; data structures are the other half of the equation.
This plays into the way that Agents (as in the context of this system, versus Pydantic AI agents) are wrapped arbitrarily. I'd favor making the conversion from a Pydantic agent to a native agent part of the system's interface design, rather than re-implementing a subset of the agentic functions in your own BaseAgent and ending up with an `agent.agent` context.
Also, since this is a web-centric application (that leverages agents) dropping all of your view functions into main.py leaves something to be desired; break up your views into logical modules based on role.
Everyone's learning, and I hope this helps someone in their journey. Kudos for putting your code out there as a resource; some of us can't help ourselves from reading it.
morkalork 2 hours ago [-]
Do you have any recommendations for articles or example projects of what a good Python project (that isn't django based) looks like in 2025? Seeing things like pydantic derived types leak everywhere seems wrong from my Java background.
tcdent 53 minutes ago [-]
Ooh, great question. I don't have a good link. I would say that most of the concepts that I'm expressing come from personal experience and an interest in optimizing my own codebases for maintainability.
Pydantic is often misunderstood, and developers who aren't familiar with typesafe-python love to try to raise criticisms of it. But the way that you should think about it is that it's essentially a replacement for a built-in type system in the context of data like a dataclass. However, Pydantic takes it further by giving you serialization and deserialization that is customizable and has integrations with, for example, SQL Alchemy where you can serialize directly from your ORM. One of the major benefits that I find is that it provides common, repeatable interfaces for validation or data formatting.
Essentially, it has become incredibly popular because it provides a consistent interface that developers understand for accomplishing these common patterns.
When it comes to "leaking" derived types through things like OpenAPI specs and documentation, they don't really expose the underlying object's functionality, but they do expose the object's structure so that you can easily generate documentation that includes the expected response bodies and expected return bodies. Whether those get serialized into JSON or something else, the parameters and types and optionality of each of those is formally defined by Pydantic in a way that's straightforward for the documentation generation to interpret.
In most cases you'll disable the generated documentation links from FastAPI in production.
reactordev 24 minutes ago [-]
Exactly this. From SQL Alchemy to pydantic model, from pydantic model to pydantic dto, from pydantic dto to json/protobuf/binary to ship over the wire…
reactordev 25 minutes ago [-]
pydantic types are designed to be shipped. Just make sure you strip any security stuff or PII. Pydantic and JSON work very very well together.
colonCapitalDee 3 hours ago [-]
I've been very happy with pydantic-ai, it blows the rest of the python ai ecosystem out of the water
gHA5 2 hours ago [-]
Are you using Pydantic AI for structured output? If so, have you also tried instructor?
Your views are not following a single convention: some of them return dictionaries, some return base JSONResponse objects, and others return properly defined Pydantic schemas. I didn't run the code, but I'd venture to guess your generated documentation is not comprehensive, nor is it cohesive.
I'd also further extend this into your agent services; passing bare dictionaries with arbitrary fields into what is supposed to be a modular logic handler is pretty outdated. You're defining a functional (methods) interface; data structures are the other half of the equation.
This plays into the way that Agents (as in the context of this system, versus Pydantic AI agents) are wrapped arbitrarily. I'd favor making the conversion from a Pydantic agent to a native agent part of the system's interface design, rather than re-implementing a subset of the agentic functions in your own BaseAgent and ending up with an `agent.agent` context.
Also, since this is a web-centric application (that leverages agents) dropping all of your view functions into main.py leaves something to be desired; break up your views into logical modules based on role.
Everyone's learning, and I hope this helps someone in their journey. Kudos for putting your code out there as a resource; some of us can't help ourselves from reading it.
Pydantic is often misunderstood, and developers who aren't familiar with typesafe-python love to try to raise criticisms of it. But the way that you should think about it is that it's essentially a replacement for a built-in type system in the context of data like a dataclass. However, Pydantic takes it further by giving you serialization and deserialization that is customizable and has integrations with, for example, SQL Alchemy where you can serialize directly from your ORM. One of the major benefits that I find is that it provides common, repeatable interfaces for validation or data formatting.
Essentially, it has become incredibly popular because it provides a consistent interface that developers understand for accomplishing these common patterns.
When it comes to "leaking" derived types through things like OpenAPI specs and documentation, they don't really expose the underlying object's functionality, but they do expose the object's structure so that you can easily generate documentation that includes the expected response bodies and expected return bodies. Whether those get serialized into JSON or something else, the parameters and types and optionality of each of those is formally defined by Pydantic in a way that's straightforward for the documentation generation to interpret.
In most cases you'll disable the generated documentation links from FastAPI in production.
just feels a bit more polished. especially testing part.
Would be great if you can add the slides or video of the presentation to the repo. Maybe also add a description and update the summary at the top?
It seems like the project is a multi-agent playground & demo to learn how to make AI agents work together?