agentgit 0.1.0__tar.gz

agentgit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AgentGit Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentgit-0.1.0/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: agentgit
+Version: 0.1.0
+Summary: Git for AI Thoughts — Checkpointing & Recovery Protocol for AI Agents
+Author: AgentGit Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/agentgit/agentgit
+Project-URL: Documentation, https://agentgit.readthedocs.io
+Project-URL: Repository, https://github.com/agentgit/agentgit
+Project-URL: Issues, https://github.com/agentgit/agentgit/issues
+Keywords: ai,agents,checkpointing,recovery,state-management,llm,reasoning,rollback,branching
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# 🧠 AgentGit — Git for AI Thoughts
+
+**An open-source Checkpointing & Recovery Protocol for AI Agents**
+
+> Save, branch, rollback, and recover an agent's "state of mind" at every reasoning step. If the model hits a bug or a timeout, it rolls back to the last logical state and tries a different path — without starting over.
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-41%20passed-brightgreen.svg)]()
+
+---
+
+## The Problem
+
+AI agents are **fragile**. When a multi-step reasoning chain fails at step 7, most frameworks throw everything away and start from scratch. That's like closing your entire Word document because you made a typo on page 3.
+
+## The Solution
+
+AgentGit gives your agent a **version-controlled brain**:
+
+| Git Concept | AgentGit Equivalent | What It Means |
+|---|---|---|
+| `git commit` | `agent.checkpoint()` | Save the agent's current "thought" |
+| `git reset` | `agent.rollback()` | Undo bad reasoning, go back to a good state |
+| `git branch` | `agent.branch()` | Explore alternative solutions in parallel |
+| `git merge` | `agent.merge()` | Combine the best ideas from different paths |
+| `git log` | `agent.history()` | View the full reasoning timeline |
+| `git diff` | `agent.diff()` | See what changed between two thought-states |
+
+---
+
+## Quick Start
+
+```bash
+pip install agentgit
+```
+
+```python
+from agentgit import AgentGit
+
+# Initialize — like 'git init' for your agent's brain
+agent = AgentGit("my-research-agent")
+
+# Step 1: Save the agent's initial understanding
+agent.checkpoint(
+    state={"task": "Find best restaurants in NYC", "status": "parsing"},
+    metadata={"confidence": 0.9},
+    description="Parsed user request",
+    logic_step="parse_input"
+)
+
+# Step 2: Agent does some work...
+agent.checkpoint(
+    state={"task": "Find best restaurants in NYC", "results": ["Le Bernardin", "Eleven Madison Park"]},
+    metadata={"confidence": 0.85},
+    description="Found top restaurants",
+    logic_step="search_restaurants"
+)
+
+# Step 3: Oh no, the API timed out on the next step!
+# No problem — just roll back.
+agent.rollback()  # Goes back to "Found top restaurants"
+
+# Or try a completely different approach
+agent.branch("alternative-search")
+agent.checkpoint(
+    state={"task": "Find best restaurants in NYC", "approach": "Use cached reviews"},
+    logic_step="cached_search"
+)
+```
+
+---
+
+## Core Features
+
+### 1. Checkpointing — Save Points for the Brain
+
+```python
+cp = agent.checkpoint(
+    state={"reasoning": "The user wants X because of Y..."},
+    metadata={"confidence": 0.87, "tokens_used": 150},
+    description="Identified user intent",
+    logic_step="intent_classification"
+)
+# Every checkpoint gets a unique ID and content hash
+print(f"Saved: {cp.id} (hash: {cp.hash})")
+```
+
+### 2. Rollback — Ctrl+Z for Thinking
+
+```python
+# Go back one step
+agent.rollback()
+
+# Go back 3 steps
+agent.rollback(steps=3)
+
+# Jump to a specific checkpoint
+agent.rollback(to_checkpoint_id="abc123")
+```
+
+### 3. Branching — Explore Multiple Approaches
+
+```python
+# Main path: conservative approach
+agent.checkpoint(state={"approach": "step-by-step"})
+
+# Branch off to try something creative
+agent.branch("creative")
+agent.checkpoint(state={"approach": "lateral-thinking"})
+
+# Go back to main if creative doesn't work
+agent.switch_branch("main")
+```
+
+### 4. Safe Execution — Automatic Error Recovery
+
+```python
+def risky_api_call(state):
+    # This might fail due to rate limits, timeouts, etc.
+    return call_external_api(state["query"])
+
+result, checkpoint = agent.safe_execute(
+    func=risky_api_call,
+    state={"query": "latest news"},
+    description="Fetch news articles",
+    max_retries=3,
+    fallback=use_cached_data  # Plan B if all retries fail
+)
+```
+
+### 5. Logic Tree — Full Decision Audit Trail
+
+```python
+print(agent.visualize_tree())
+```
+
+Output:
+```
+└── ✅ Task received [de3eec5f]
+    └── ✅ Plan created [3a7996fa]
+        ├── ❌ API call failed [372aabc7]
+        ├── ✅ Used cache instead [a4d4e95e]
+        └── ✅ Retry succeeded [330a3284]
+            └── ✅ Summary generated [67f8369a]
+```
+
+### 6. Decorators — Zero-Code-Change Integration
+
+```python
+from agentgit.decorators import agentgit_step
+
+@agentgit_step("analyze_data")
+def analyze(state):
+    # Your existing code — unchanged!
+    return {"analysis": process(state["data"])}
+
+# Automatically checkpointed, with rollback on failure
+result = analyze({"data": raw_data})
+```
+
+---
+
+## Recovery Strategies
+
+| Strategy | When to Use | What It Does |
+|---|---|---|
+| `RetryWithBackoff` | API timeouts, rate limits | Waits longer between each retry |
+| `AlternativePathStrategy` | Logic dead-ends | Switches to a different approach |
+| `DegradeGracefully` | Resource limits | Produces simpler output |
+| `CompositeStrategy` | Complex scenarios | Chains multiple strategies |
+
+```python
+from agentgit import AgentGit
+from agentgit.strategies import RetryWithBackoff, DegradeGracefully, CompositeStrategy
+
+agent = AgentGit(
+    "resilient-agent",
+    recovery_strategies=[
+        CompositeStrategy([
+            RetryWithBackoff(base_delay=1.0, max_delay=30.0),
+            DegradeGracefully(),
+        ])
+    ]
+)
+```
+
+---
+
+## Storage Backends
+
+```python
+from agentgit.storage import FileSystemStorage, SQLiteStorage
+
+# File-based (great for debugging — you can read the JSON files)
+agent = AgentGit("my-agent", storage_backend=FileSystemStorage(".agentgit"))
+
+# SQLite (fast queries, good for production)
+agent = AgentGit("my-agent", storage_backend=SQLiteStorage("agent.db"))
+```
+
+---
+
+## CLI
+
+```bash
+# Run the interactive demo
+agentgit demo
+
+# View checkpoint history
+agentgit log
+
+# Visualize the reasoning tree
+agentgit tree
+
+# List branches
+agentgit branches
+
+# Compare two checkpoints
+agentgit diff abc123 def456
+
+# View metrics
+agentgit metrics
+```
+
+---
+
+## Framework Integration
+
+### LangChain
+```python
+from agentgit.decorators import AgentGitMiddleware
+
+middleware = AgentGitMiddleware("langchain-agent")
+wrapped_chain = middleware.wrap(my_chain.invoke, "process_query")
+result = wrapped_chain({"input": "Hello"})
+```
+
+### Any Python Agent
+```python
+from agentgit.decorators import checkpoint_context
+
+with checkpoint_context(description="Data processing") as ctx:
+    result = process_data(data)
+    ctx.state = {"result": result}
+# Auto-rolls back on exception
+```
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────┐
+│                   Your AI Agent                   │
+├──────────────────────────────────────────────────┤
+│    Decorators & Middleware (agentgit.decorators)   │
+├──────────────────────────────────────────────────┤
+│         AgentGit Core Engine (agentgit.engine)    │
+│  ┌─────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ │
+│  │Checkpoint│ │ Branch │ │Rollback│ │Logic Tree│ │
+│  └─────────┘ └────────┘ └────────┘ └──────────┘ │
+├──────────────────────────────────────────────────┤
+│    Recovery Strategies (agentgit.strategies)      │
+├──────────────────────────────────────────────────┤
+│      Serializers (agentgit.serializers)           │
+├──────────────────────────────────────────────────┤
+│   Storage Backends: FileSystem │ SQLite │ Memory  │
+└──────────────────────────────────────────────────┘
+```
+
+---
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

agentgit-0.1.0/README.md

@@ -0,0 +1,280 @@
+# 🧠 AgentGit — Git for AI Thoughts
+
+**An open-source Checkpointing & Recovery Protocol for AI Agents**
+
+> Save, branch, rollback, and recover an agent's "state of mind" at every reasoning step. If the model hits a bug or a timeout, it rolls back to the last logical state and tries a different path — without starting over.
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-41%20passed-brightgreen.svg)]()
+
+---
+
+## The Problem
+
+AI agents are **fragile**. When a multi-step reasoning chain fails at step 7, most frameworks throw everything away and start from scratch. That's like closing your entire Word document because you made a typo on page 3.
+
+## The Solution
+
+AgentGit gives your agent a **version-controlled brain**:
+
+| Git Concept | AgentGit Equivalent | What It Means |
+|---|---|---|
+| `git commit` | `agent.checkpoint()` | Save the agent's current "thought" |
+| `git reset` | `agent.rollback()` | Undo bad reasoning, go back to a good state |
+| `git branch` | `agent.branch()` | Explore alternative solutions in parallel |
+| `git merge` | `agent.merge()` | Combine the best ideas from different paths |
+| `git log` | `agent.history()` | View the full reasoning timeline |
+| `git diff` | `agent.diff()` | See what changed between two thought-states |
+
+---
+
+## Quick Start
+
+```bash
+pip install agentgit
+```
+
+```python
+from agentgit import AgentGit
+
+# Initialize — like 'git init' for your agent's brain
+agent = AgentGit("my-research-agent")
+
+# Step 1: Save the agent's initial understanding
+agent.checkpoint(
+    state={"task": "Find best restaurants in NYC", "status": "parsing"},
+    metadata={"confidence": 0.9},
+    description="Parsed user request",
+    logic_step="parse_input"
+)
+
+# Step 2: Agent does some work...
+agent.checkpoint(
+    state={"task": "Find best restaurants in NYC", "results": ["Le Bernardin", "Eleven Madison Park"]},
+    metadata={"confidence": 0.85},
+    description="Found top restaurants",
+    logic_step="search_restaurants"
+)
+
+# Step 3: Oh no, the API timed out on the next step!
+# No problem — just roll back.
+agent.rollback()  # Goes back to "Found top restaurants"
+
+# Or try a completely different approach
+agent.branch("alternative-search")
+agent.checkpoint(
+    state={"task": "Find best restaurants in NYC", "approach": "Use cached reviews"},
+    logic_step="cached_search"
+)
+```
+
+---
+
+## Core Features
+
+### 1. Checkpointing — Save Points for the Brain
+
+```python
+cp = agent.checkpoint(
+    state={"reasoning": "The user wants X because of Y..."},
+    metadata={"confidence": 0.87, "tokens_used": 150},
+    description="Identified user intent",
+    logic_step="intent_classification"
+)
+# Every checkpoint gets a unique ID and content hash
+print(f"Saved: {cp.id} (hash: {cp.hash})")
+```
+
+### 2. Rollback — Ctrl+Z for Thinking
+
+```python
+# Go back one step
+agent.rollback()
+
+# Go back 3 steps
+agent.rollback(steps=3)
+
+# Jump to a specific checkpoint
+agent.rollback(to_checkpoint_id="abc123")
+```
+
+### 3. Branching — Explore Multiple Approaches
+
+```python
+# Main path: conservative approach
+agent.checkpoint(state={"approach": "step-by-step"})
+
+# Branch off to try something creative
+agent.branch("creative")
+agent.checkpoint(state={"approach": "lateral-thinking"})
+
+# Go back to main if creative doesn't work
+agent.switch_branch("main")
+```
+
+### 4. Safe Execution — Automatic Error Recovery
+
+```python
+def risky_api_call(state):
+    # This might fail due to rate limits, timeouts, etc.
+    return call_external_api(state["query"])
+
+result, checkpoint = agent.safe_execute(
+    func=risky_api_call,
+    state={"query": "latest news"},
+    description="Fetch news articles",
+    max_retries=3,
+    fallback=use_cached_data  # Plan B if all retries fail
+)
+```
+
+### 5. Logic Tree — Full Decision Audit Trail
+
+```python
+print(agent.visualize_tree())
+```
+
+Output:
+```
+└── ✅ Task received [de3eec5f]
+    └── ✅ Plan created [3a7996fa]
+        ├── ❌ API call failed [372aabc7]
+        ├── ✅ Used cache instead [a4d4e95e]
+        └── ✅ Retry succeeded [330a3284]
+            └── ✅ Summary generated [67f8369a]
+```
+
+### 6. Decorators — Zero-Code-Change Integration
+
+```python
+from agentgit.decorators import agentgit_step
+
+@agentgit_step("analyze_data")
+def analyze(state):
+    # Your existing code — unchanged!
+    return {"analysis": process(state["data"])}
+
+# Automatically checkpointed, with rollback on failure
+result = analyze({"data": raw_data})
+```
+
+---
+
+## Recovery Strategies
+
+| Strategy | When to Use | What It Does |
+|---|---|---|
+| `RetryWithBackoff` | API timeouts, rate limits | Waits longer between each retry |
+| `AlternativePathStrategy` | Logic dead-ends | Switches to a different approach |
+| `DegradeGracefully` | Resource limits | Produces simpler output |
+| `CompositeStrategy` | Complex scenarios | Chains multiple strategies |
+
+```python
+from agentgit import AgentGit
+from agentgit.strategies import RetryWithBackoff, DegradeGracefully, CompositeStrategy
+
+agent = AgentGit(
+    "resilient-agent",
+    recovery_strategies=[
+        CompositeStrategy([
+            RetryWithBackoff(base_delay=1.0, max_delay=30.0),
+            DegradeGracefully(),
+        ])
+    ]
+)
+```
+
+---
+
+## Storage Backends
+
+```python
+from agentgit.storage import FileSystemStorage, SQLiteStorage
+
+# File-based (great for debugging — you can read the JSON files)
+agent = AgentGit("my-agent", storage_backend=FileSystemStorage(".agentgit"))
+
+# SQLite (fast queries, good for production)
+agent = AgentGit("my-agent", storage_backend=SQLiteStorage("agent.db"))
+```
+
+---
+
+## CLI
+
+```bash
+# Run the interactive demo
+agentgit demo
+
+# View checkpoint history
+agentgit log
+
+# Visualize the reasoning tree
+agentgit tree
+
+# List branches
+agentgit branches
+
+# Compare two checkpoints
+agentgit diff abc123 def456
+
+# View metrics
+agentgit metrics
+```
+
+---
+
+## Framework Integration
+
+### LangChain
+```python
+from agentgit.decorators import AgentGitMiddleware
+
+middleware = AgentGitMiddleware("langchain-agent")
+wrapped_chain = middleware.wrap(my_chain.invoke, "process_query")
+result = wrapped_chain({"input": "Hello"})
+```
+
+### Any Python Agent
+```python
+from agentgit.decorators import checkpoint_context
+
+with checkpoint_context(description="Data processing") as ctx:
+    result = process_data(data)
+    ctx.state = {"result": result}
+# Auto-rolls back on exception
+```
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────┐
+│                   Your AI Agent                   │
+├──────────────────────────────────────────────────┤
+│    Decorators & Middleware (agentgit.decorators)   │
+├──────────────────────────────────────────────────┤
+│         AgentGit Core Engine (agentgit.engine)    │
+│  ┌─────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ │
+│  │Checkpoint│ │ Branch │ │Rollback│ │Logic Tree│ │
+│  └─────────┘ └────────┘ └────────┘ └──────────┘ │
+├──────────────────────────────────────────────────┤
+│    Recovery Strategies (agentgit.strategies)      │
+├──────────────────────────────────────────────────┤
+│      Serializers (agentgit.serializers)           │
+├──────────────────────────────────────────────────┤
+│   Storage Backends: FileSystem │ SQLite │ Memory  │
+└──────────────────────────────────────────────────┘
+```
+
+---
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

agentgit-0.1.0/agentgit/__init__.py

@@ -0,0 +1,50 @@
+"""
+AgentGit — Git for AI Thoughts
+================================
+An open-source Checkpointing & Recovery Protocol for AI Agents.
+
+Save, branch, rollback, and recover agent "state of mind" at every reasoning step.
+Think of it as version control for AI cognition.
+
+Quick Start:
+    from agentgit import AgentGit
+
+    agent = AgentGit("my-agent")
+    
+    agent.checkpoint(
+        state={"reasoning": "Analyzing user query..."},
+        metadata={"step": "initial_analysis"}
+    )
+    
+    # If something goes wrong, rollback:
+    agent.rollback()
+    
+    # Or branch to explore alternative reasoning:
+    agent.branch("alternative-approach")
+
+License: MIT
+"""
+
+__version__ = "0.1.0"
+__author__ = "AgentGit Contributors"
+
+from .engine import AgentGit, Checkpoint, Branch, LogicTree
+from .strategies import RecoveryStrategy, RetryWithBackoff, AlternativePathStrategy
+from .serializers import StateSerializer, JSONSerializer, PickleSerializer
+from .storage import StorageBackend, FileSystemStorage, SQLiteStorage
+
+__all__ = [
+    "AgentGit",
+    "Checkpoint",
+    "Branch",
+    "LogicTree",
+    "RecoveryStrategy",
+    "RetryWithBackoff",
+    "AlternativePathStrategy",
+    "StateSerializer",
+    "JSONSerializer",
+    "PickleSerializer",
+    "StorageBackend",
+    "FileSystemStorage",
+    "SQLiteStorage",
+]