Metadata-Version: 2.4
Name: gitlord
Version: 0.2.0
Summary: Agent orchestration framework with git-backed storage
Author-email: Yashneil Gajjala <yashneil75@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/yashneil75/gitlord
Project-URL: Repository, https://github.com/yashneil75/gitlord
Project-URL: Issues, https://github.com/yashneil75/gitlord/issues
Keywords: git,agent,orchestration,ai,mcp,litellm,chromadb,rag,rewindable,session
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Provides-Extra: all
Requires-Dist: litellm>=1.40; extra == "all"
Requires-Dist: chromadb>=0.5; extra == "all"
Requires-Dist: typer>=0.9; extra == "all"
Requires-Dist: ulid-py>=1.1; extra == "all"
Requires-Dist: tiktoken>=0.7; extra == "all"
Requires-Dist: mcp>=1.27; extra == "all"
Provides-Extra: mcp
Requires-Dist: mcp>=1.27; extra == "mcp"
Provides-Extra: litellm
Requires-Dist: litellm>=1.40; extra == "litellm"
Provides-Extra: chromadb
Requires-Dist: chromadb>=0.5; extra == "chromadb"
Provides-Extra: cli
Requires-Dist: typer>=0.9; extra == "cli"
Provides-Extra: ulid
Requires-Dist: ulid-py>=1.1; extra == "ulid"
Dynamic: license-file

# GitLord

**Git for AI Agents.**

GitLord turns Git into a database for autonomous agents. Every agent action becomes a version-controlled event — inspectable, replayable, forkable.

---

## Why GitLord?

AI agents are powerful but untrustworthy. When something goes wrong, you can't answer basic questions:

- Why did the agent make that decision?
- Which tool call caused the failure?
- Can we reproduce the execution?
- Can we branch from an earlier point?

Most frameworks lose this information. GitLord makes execution history a first-class primitive.

---

## How It Works

Every turn is a Git commit on a branch under `refs/agents/`:

```
refs/agents/my-agent
  commit 001 → user prompt
  commit 002 → assistant response
  commit 003 → tool call
  commit 004 → tool result
  commit 005 → subagent result
```

Git's primitives become agent primitives:

| Git Concept | Agent Concept |
|-------------|---------------|
| commits | agent events |
| branches | agent timelines |
| objects | durable state |
| history | memory |
| diffs | behavior changes |
| refs | agent identity |

---

## Features

### Inspect Everything

See exactly what an agent did, turn by turn. Every tool call, every decision, every failure — all version-controlled.

### Rewind Failures

Failed execution doesn't destroy history. Rewind to any checkpoint and try a different approach.

```
A --- B --- C --- D (failed)
       \
        E --- F (new attempt)
```

### Fork Alternative Approaches

Explore multiple solutions in parallel. Each branch maintains its own history.

### Track Subagents

Subagents run on their own branches with isolated histories. Results flow back to parents via Git trailers.

### Searchable History

Query past executions by turn, agent, tokens, errors, or semantic similarity. Your agents don't just remember documents — they remember experiences.

### Two-Repo Architecture

Clean separation between memory and workspace:

- **Log repo** — turn history, tool calls, metadata (no working-tree checkout needed)
- **Workspace repo** — actual files the agent reads/writes

---

## Install

```bash
pip install gitlord           # core (just pydantic)
pip install gitlord[all]      # everything
pip install gitlord[mcp]      # MCP server support
pip install gitlord[litellm]  # LLM model routing
pip install gitlord[chromadb] # vector index for RAG
```

---

## Quickstart

```python
from gitlord import Session, SessionConfig, Turn, TurnRole

config = SessionConfig(log_repo_path="log")
session = Session.create("my-agent", config)
session.append_user_turn("Hello, what's the weather in London?")

turns = session.get_turns()
for t in turns:
    print(f"  [{t.role}] {t.content[:80]}")
```

---

## CLI

```bash
gitlord run my-session                    # run a session
gitlord log my-session                    # view turn history
gitlord tree my-session                   # view branch structure
gitlord show <sha>                        # show turn JSON
gitlord rewind my-session <sha>           # rewind to checkpoint
gitlord diff <sha-a> <sha-b>              # diff two turns
gitlord index                             # rebuild search index
gitlord trim my-session [N]              # trim to N turns
```

---

## Architecture

| Module | What It Does |
|--------|--------------|
| `gitlord.git` | Git plumbing — tree/commit construction, CAS updates, orphan branches |
| `gitlord.session` | Session lifecycle — create, resume, append turns, rewind |
| `gitlord.subagent` | Subagent management — spawn, complete, drain, trim |
| `gitlord.context` | Context assembly — dedup, summarization, token budget |
| `gitlord.mcp` | MCP server lifecycle — tool discovery, crash recovery |
| `gitlord.model` | LLM router — tool schema translation, retry/fallback |
| `gitlord.rag` | Vector index — ChromaDB wrapper, MMR search |
| `gitlord.index` | JSON index — rebuild from git log |
| `gitlord.query` | In-memory query layer — filter, group, aggregate |
| `gitlord.cli` | CLI — run, log, tree, show, rewind, diff, index, trim |

---

## The Vision

Software has Git. Documents have version history. Code has commits.

AI agents should have the same thing.

GitLord is a version control system for autonomous intelligence.

---

## License

MIT
