Metadata-Version: 2.4
Name: gistfs
Version: 0.1.0
Summary: Use GitHub Gists as a persistent key-value filesystem — ideal for AI agent memory
Project-URL: Homepage, https://github.com/HerveMignot/gistfs
Project-URL: Repository, https://github.com/HerveMignot/gistfs
Project-URL: Issues, https://github.com/HerveMignot/gistfs/issues
Author: Hervé Mignot
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,filesystem,gist,github,llm,memory
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: requests>=2.28
Provides-Extra: all
Requires-Dist: langgraph-checkpoint>=2.0; extra == 'all'
Requires-Dist: llama-index-core>=0.11; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: python-dotenv>=1.0; extra == 'dev'
Provides-Extra: langgraph
Requires-Dist: langgraph-checkpoint>=2.0; extra == 'langgraph'
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.11; extra == 'llamaindex'
Description-Content-Type: text/markdown

# gistfs

Use GitHub Gists as a persistent key-value filesystem — ideal for AI agent memory.

## Install

```bash
pip install gistfs
```

With optional integrations:

```bash
pip install gistfs[llamaindex]   # LlamaIndex KVStore
pip install gistfs[langgraph]    # LangGraph BaseStore
pip install gistfs[all]          # everything
```

## Quick start

### Creating a new gist

No need to create a gist manually — bootstrap one from code:

```python
from gistfs import GistFS

gfs = GistFS.create(description="my agent memory")
print(gfs.gist_id)  # save this for later

# Or with GistMemory:
from gistfs import GistMemory
mem = GistMemory.create(description="my agent memory")
```

### As a filesystem (context manager)

```python
from gistfs import GistFS

with GistFS(gist_id="your_gist_id") as gfs:
    gfs.write("config.json", {"model": "gpt-4", "temperature": 0.7})
    config = gfs.read("config.json")
    print(gfs.list_files())
    gfs.delete("config.json")
```

### File-like interface

```python
with GistFS(gist_id="your_gist_id") as gfs:
    with gfs.open("notes.txt", "w") as f:
        f.write("hello world")

    with gfs.open("notes.txt", "r") as f:
        content = f.read()

    with gfs.open("notes.txt", "a") as f:
        f.write("\nappended line")
```

### As AI agent memory

```python
from gistfs import GistMemory

with GistMemory(gist_id="your_gist_id") as mem:
    mem.put("conversation_1", {"messages": [{"role": "user", "content": "hi"}]})
    history = mem.get("conversation_1")
    all_data = mem.get_all()
    mem.delete("conversation_1")
```

### LlamaIndex integration

```python
from gistfs.integrations.llamaindex import GistKVStore

store = GistKVStore(gist_id="your_gist_id")
store.put("doc1", {"text": "hello world"}, collection="docstore")
doc = store.get("doc1", collection="docstore")
```

### LangGraph integration

```python
from gistfs.integrations.langgraph import GistStore

store = GistStore(gist_id="your_gist_id")
store.put(("user", "prefs"), "theme", {"value": "dark"})
item = store.get(("user", "prefs"), "theme")
```

## Authentication

Set the `GITHUB_TOKEN` environment variable with a GitHub personal access token that has `gist` scope. Read-only operations on public gists work without a token.

```bash
export GITHUB_TOKEN=ghp_your_token_here
```

Or pass it directly:

```python
gfs = GistFS(gist_id="abc123", token="ghp_...")
```
