typeagent-py: a Python port of TypeAgent's structured RAG pipeline

An explicit warning about where your input goes

The most important paragraph in the readme is the warning, and it comes before anything else.

This library will send its input to an LLM hosted by a third party. Don't use it to index confidential information.

That is a short, plain statement of the constraint that governs every other decision in the project. A structured RAG pipeline that reasons over a corpus of messages needs a language model to interpret what the user is asking and to structure the answer, and the model the library talks to is not one you run. So the corpus travels.

This is not a defect and it is not an oversight. The project is explicit in three places about what it is: this is an experimental prototype, working toward a shared understanding of the MVP for structured RAG, and this is sample code, an in-progress project aiming at a Pythonic translation of TypeAgent KnowPro and a few related packages from TypeScript to Python.

So the intended use is learning and prototyping rather than production. The word shared understanding in the first description is the giveaway, this is a project trying to work out the shape of the design in Python and in the open, with the design documents and slides published alongside it.

The documentation set follows that. There is a docs directory with its own README, the PyBay '25 slides as both a PowerPoint and a PDF, and a video of the PyBay '25 talk. Someone wanting to understand Structured RAG can read the design and watch the talk without reading a line of the source.

The package metadata lists the authors as Guido van Rossum, Steven Lucco and Umesh Madan, and the homepage of the project is the TypeAgent repository that the port is derived from.

The Python package and what the index actually holds

The distribution is named typeagent, the project description in the manifest is Incremental message indexing and querying pipelines using Structured RAG, and the version is 0.5.0.dev.

That version string is itself informative. A dev suffix means the published artefact is a development snapshot, not a tagged release, and combined with the Development Status :: 3 - Alpha classifier the intent is clear.

The subject matter is messages rather than documents. The Makefile's evaluation target loads a test corpus from tests/testdata, an index directory for Episode 53 by Adrian Tchaikovsky, and compares against answer and search results fixtures with the same episode name.

That naming is worth pausing on. A fictional podcast or serialised narrative broken into episodes is a good test corpus for this kind of system, because it has structure. Episodes have a beginning, a middle and an end, characters recur, and questions can have answers grounded in a specific moment. The answer and search results fixtures suggest the harness is checking not only that a query returns something but that it returns the right thing, which is the difference between a demo and an evaluation.

The Typing :: Typed classifier and the CPython implementation marker indicate a fully typed package, and the Python version classifiers run from 3.12 to 3.15 with requires-python set to >=3.12.

The repository also carries a .env-template, which is where the LLM endpoint and credentials for the third party model are configured, plus a CHANGELOG.md, a NOTES.md, a TODO.md, an AGENTS.md and a SECURITY.md, and the src/ tree with the typeagent package inside it.

The Makefile is the real documentation

The Makefile opens with a comment that says more about the project's culture than any design document would. This is Guido's Makefile. Please don't make it complicated.

The default target chains the whole pipeline.

all: format ruff check test build

Each stage is a single tool invocation, and the choice of tool tells you what the project values. Formatting runs isort and then black with a py312 target across src, tests, tools and examples. Ruff handles linting with the comment that it is narrowly scoped to deterministically banning wildcard imports, because AGENTS.md carries the import guidelines. Tests run pytest, and coverage has its own target that uses COVERAGE_PROCESS_START with a .coveragerc and combines the results.

The check stage has a comment explaining why it does less than you would expect. It runs pyright only for the lowest and the highest Python version, because running it for all versions takes too much time and does not add enough diagnostic power.

That is a defensible trade and an unusual one to see written down. Most projects either type check against one version or against every version they support. Here the decision is made explicitly and the reason is cost.

The remaining targets are the ones that make the project explorable. The demo target runs a query tool, compare runs the same tool in batch mode, eval deletes an eval.db and rebuilds it from the test data before running the batch comparison against the answer and search fixtures, mcp starts the MCP server in dev mode, and profile runs a cProfile of the search over an index.

The profile and scaling targets are interesting because they point at the thing a RAG prototype has to get right, which is search latency rather than model quality.

Dependency bounds written as policy, with a reason

The pyproject.toml carries a comment block that is one of the more unusual dependency policies you will read in a Python project.

The comment says these bounds ship in the wheel metadata, so they constrain every project that depends on typeagent. It instructs keeping the lower bounds as low as they still work, explaining that when two packages demand different minimums of a shared dependency the result is an unsolvable resolution for the user in the middle. So the instruction is not to raise a floor just because a newer release exists, only when the code actually requires it, and to add an upper bound only for a known incompatibility.

Then it points at mcp as the example.

The dependency list shows mcp[cli]>=1.12.1,<2, and the comment above it explains exactly why: mcp 2.0 dropped mcp.server.fastmcp, and src/typeagent/mcp/server.py needs porting to the new MCPServer API before the cap can be lifted.

That is a specific, verifiable engineering constraint rather than a vague pin, and it tells you two things about the project. The MCP integration is live rather than aspirational, since there is a server module and a Makefile target that runs mcp dev on it. And the upper bound is a known incompatibility with a documented remediation path, not inertia.

The rest of the visible dependencies include azure-identity at 1.22.0 or newer for authentication to Azure services, numpy at 2.5.2 or newer for Python 3.12 and above, and colorama at 0.4.6 or newer.

The build backend is uv_build, which means the package is built with uv rather than setuptools, and the repository carries a uv.lock. That is consistent with a project where every Makefile target runs through uv run, so the environment is always the locked one.

Where this prototype is the wrong thing to build on

Three limits, and the first two are stated in the project's own documentation.

The first is that this is sample code for an experimental prototype. The readme says so twice and in different words, and the version is 0.5.0.dev with an alpha development status. That does not make it useless, it makes it a reference implementation rather than a dependency you would pin in a service and expect to still work after two years of upstream churn.

The second is the LLM data boundary. The warning is unambiguous, don't use it to index confidential information. If your corpus is internal documents, interview transcripts, customer records or anything under a confidentiality obligation, this library is out regardless of how good the implementation is, unless you point it at a model you control, which the documentation does not describe how to do.

The third is the Python version floor and the dependency shape. requires-python is >=3.12 and the classifiers run to 3.15, so this is not something you drop into an existing 3.9 service. And the whole approach is tied to a specific LLM's behaviour for structuring, which is the kind of dependency that shifts underneath you when the provider updates a model.

The alternatives differ in what they are. TypeAgent itself is the TypeScript original with the full knowPro packages, and it is the reference implementation of the design rather than a port of it, so if you want to read the primary source that is where to read it. A conventional RAG stack, an embedding store plus a vector database plus a retrieval library, gives you production support and no data boundary surprises at the cost of the structured message model that this project is exploring. And a notebook built on a hosted model API gives you the same third party LLM boundary without a library at all, which for evaluating whether Structured RAG is worth the complexity is the cheaper experiment.

Editorial conclusion

typeagent-py suits a Python developer who wants to understand how Structured RAG works, or who wants to build on the same ideas in a Python codebase, and the Makefile targets give a quick route to running the demos and the evaluation harness. It does not suit a production service that needs a supported library, since the project describes itself as an experimental prototype and sample code, and it does not suit anyone whose corpus is confidential, because the documentation warns in terms that the library sends its input to an LLM hosted by a third party. Before using it, read the warning in the readme and decide whether your data can leave your machine, and check that the version you install matches the Python you run, since the package requires Python 3.12 or newer and is published as 0.5.0.dev.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. microsoft/typeagent-py on GitHub
4. README