Metadata-Version: 2.4
Name: loregpt
Version: 0.1.1
Summary: Python SDK for Lore — coordination memory for multi-agent AI systems: create runs, write events, and fetch read-your-writes context packs.
Project-URL: Homepage, https://loregpt.ai
Project-URL: Repository, https://github.com/lore-gpt/lore
Project-URL: Issues, https://github.com/lore-gpt/lore/issues
Author: The LoreGPT Authors
License-Expression: Apache-2.0
Keywords: agents,ai,context,coordination,llm,mcp,memory,multi-agent,read-your-writes
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Description-Content-Type: text/markdown

# loregpt

Python SDK for **[Lore](https://github.com/lore-gpt/lore)** — the open-source coordination memory layer
for multi-agent AI systems. Create runs, write events, and fetch read-your-writes context packs.

> 🚧 **Pre-release.** Lore is building in the open toward `v0.1`; this SDK tracks the live API.

**Compatibility.** SDK `0.1.x` targets the Lore **v1** API (server `≥ 0.0.1`). The SDK and the server version
independently — match on the API version, not the release number.

## Install

```bash
pip install loregpt
```

Requires Python 3.10+. One dependency, [httpx](https://www.python-httpx.org/), for connection pooling and a
shared sync/async transport — the de-facto standard of the AI-Python ecosystem.

## Usage

```python
lore = LoreClient(api_key=api_key)

run = lore.create_run()
result = lore.write(
    run_id=run.run_id,
    agent_id="researcher",
    content="Auth flow moved to v2 - PR #42 merged",
)

pack = lore.pack(
    run_id=run.run_id,
    query="current state of auth work",
    scopes={"team": "platform"},
    min_seq=result.seq,
    token_budget=2000,
)

covered_seq = pack.covered_seq  # >= result.seq -> read-your-writes, guaranteed
saved_tokens = pack.saved_tokens  # estimated tokens saved by packing
```

`write` takes exactly one of `content` (a string, wrapped as `{"content": ...}`) or `payload` (an opaque
dict); `write_state(run_id=..., agent_id=..., entity=..., predicate=..., value=...)` writes one working-memory
fact seen immediately by a same-run reader.

### Async

`AsyncLoreClient` has the same methods with `await`:

```python
async with AsyncLoreClient(api_key=api_key) as lore:
    run = await lore.create_run()
    result = await lore.write(run_id=run.run_id, agent_id="researcher", content="hello")
    pack = await lore.pack(run_id=run.run_id, query="state of work", min_seq=result.seq)
```

## Errors

Every failure raises a `LoreError`. Server errors carry the machine `code` (discriminate on the class or
`.code`, never string-match) and `.http_status`; transport and parse failures are distinct classes. Requests
are **not** retried (a write is not idempotent) — a failure surfaces so the caller decides.

```python
from loregpt import LoreError, NotFoundError

try:
    pack = lore.pack(run_id=run_id, query="...", min_seq=999)
except NotFoundError:
    ...  # unknown run, or not this key's project
except LoreError as err:
    print(err.code)  # e.g. "min_seq_out_of_range", "model_mismatch", "unauthorized", "connection"
```

`LoreClient(api_key, *, base_url="http://localhost:8080", timeout=..., headers=..., transport=...)` — pass a
custom httpx `transport` for a proxy, instrumentation, or tests.

- Website: **https://loregpt.ai**
- Source & RFCs: **https://github.com/lore-gpt/lore**

License: Apache-2.0
