MahaCata
MahaCata runs AI agents on your data, and keeps a record of each run that you can check later.
An agent’s answer is only as good as what you know about how it got it. You need to know which data it read, and which version of that data. You also need the prompt, the model and each tool that it called. The data changes after the run, and so do the prompt and the model. So a month later, nobody can say for sure what the agent saw.
MahaCata answers that in three ways. First, code names its data by a name that stays the same when the data moves, and MahaCata pins the version that each run reads. Second, it runs the agent in a folder of its own, where the inputs are read-only. Third, it records each step of the run as an event, and each event holds the hash of the one before it. A later change to the record breaks that chain, so a check finds it.
When the run file names a store for runs, MahaCata commits the record and the agent’s answers there together, under the name of the run. A reviewer can then ask which runs read a file, and which version each one saw. They can also check that no one has changed an answer or the record since.
MahaCata is three Python packages that work together.
- provcat resolves catalog URIs. A catalog URI names a dataset, a model, a prompt or some code in words that stay the same when the storage changes. provcat turns it into the URI of a store, such as S3, lakeFS, GitHub or Hugging Face, or into a pinned version. It reads the object, or fetches it into a local cache and returns the path. A local file needs no cache. It writes to every store except GitHub and Hugging Face. It commits in lakeFS and in versioned buckets, branches in lakeFS and in any bucket, and merges in lakeFS. It makes read-only snapshots of pinned versions.
- provrun runs agents and model calls on data that provcat resolves. It asks a broker for each input, stages provcat’s read-only snapshots of them and runs the agent. It records the evidence of the run as a chain of hashed events.
- provevi stores, reads and checks the evidence of runs. Its command is
prove. Phases 1 to 5 of its seven are built. They give a SQLite store that answers questions across runs, a telemetry policy that provrun applies, and a copy of each run in MLflow. They also give a live feed of a run, and they keep experiments as versioned objects in the catalog. Each run names its experiment at its version. What provevi does shows it with examples, and its tour runs them. The design and the plan say what comes next.
provrun depends on provevi and provcat, and provevi depends on provcat. provcat depends on neither. What MahaCata does follows one file through all three.
Start here
| To do this | Read |
|---|---|
| Learn the three packages together, by running an agent on a report and checking what it did | The tutorial |
| Learn provcat alone, step by step | The provcat tutorial |
| Learn provrun alone, step by step | The provrun tutorial |
| Learn provevi alone, step by step | The provevi tutorial |
| See how the three packages work together, with one example from each | What MahaCata does |
| See what provcat does, with examples | What provcat does |
| Run provcat on your own machine, step by step | A runnable tour of provcat |
| See what provrun does, with examples | What provrun does |
| Run provrun on your own machine, from one file in a store to the evidence of its runs | A runnable tour of provrun |
| Look up provrun’s run file, library, telemetry policy and limits | provrun |
| See what provevi does with the evidence of runs, with examples | What provevi does |
| Run provevi on your own machine, step by step | A runnable tour of provevi |
| Install lakeFS, etcd and the tools that the tests need, and run the tests | Setup |
| Learn how the parts of provcat fit together | Design |
| Learn what a write and a commit guarantee | Transactions |
| Set up one lakeFS that keeps orgs apart | A reference lakeFS target |
| Read why provrun is built as it is | The provrun plan |
| Read how the evidence store will be built | The provevi design and plan |
| Look up a class or a function | Reference |
Look up the provc commands, URI forms, stores and configuration |
The provcat reference |
Look up the prove commands, the stores, the tables and the policy’s keys |
The provevi reference |
Install
You need Python 3.13 and uv. provcat, provrun and provevi are not on PyPI, so clone the repository:
git clone https://github.com/rahuldave/MahaCata
cd MahaCata
uv sync
uv run provc --help
uv run provr --helpThis site
smalldocs builds this site from the folder docs.
uv run --group docs smalldocs preview docs