Metadata-Version: 2.4
Name: gitlord
Version: 0.1.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

Agent orchestration framework with Git-backed storage. Every turn is a Git commit — inspectable, rewindable, forkable.

## Quickstart

```bash
pip install gitlord[all]
```

```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]}")
```

## Install

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

## Architecture

| Module | What |
|--------|------|
| `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, cache |
| `gitlord.mcp` | MCP server lifecycle — tool discovery, call, 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.cli` | CLI — `gitlord run`, `log`, `tree`, `show`, `rewind`, `diff`, `index` |

## How it works

Every turn is a Git commit on a branch under `refs/agents/`:
- `refs/agents/<session-id>` — session branch
- `refs/agents/sub/<session-id>/<ulid>` — subagent branches

Turn content is stored as JSON blobs in a `turns/` subdirectory in the tree.
Git trailers encode turn metadata (turn number, type, agent, tokens).
Subagent results are linked via `Subagent-Result` trailer.

## 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
```

## Development

```bash
pip install -e ".[all]"
pytest tests/
```

## License

MIT
