Python SDK

loregpt is the official Python client. It needs Python 3.10+ and one runtime dependency (httpx), and ships both a synchronous LoreClient and an asynchronous AsyncLoreClient with the same surface.

Install

pip install loregpt

Usage

Create a client, write an event, and pack a context. The seq a write returns is the min_seq of a later pack — that's the read-your-writes guarantee.

# Adapted from clients/python/examples/hero.py (type-checked in CI).
import os

from loregpt import LoreClient

lore = LoreClient(api_key=os.environ["LORE_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"},  # optional retrieval filter
    min_seq=result.seq,
    token_budget=2000,
)

covered_seq = pack.covered_seq  # >= result.seq once distilled; until then the write is in the raw tail
saved_tokens = pack.saved_tokens  # a coarse estimate vs raw history; small packs may round to 0

The client exposes create_run(), write(...), write_state(...) (a working-memory fact through the low-latency lane), and pack(...). write takes exactly one of content or payload.

Async

AsyncLoreClient has the same methods with await, and works as an async context manager:

# Synced from clients/python/examples/async_hero.py (type-checked in CI).
import asyncio
import os

from loregpt import AsyncLoreClient


async def main() -> None:
    async with AsyncLoreClient(api_key=os.environ["LORE_API_KEY"]) as lore:
        run = await lore.create_run()
        result = await lore.write(run_id=run.run_id, agent_id="researcher", content="hello memory")
        pack = await lore.pack(run_id=run.run_id, query="state of work", min_seq=result.seq)
        print(pack.covered_seq, pack.saved_tokens)


if __name__ == "__main__":
    asyncio.run(main())

Client options

Both LoreClient(...) and AsyncLoreClient(...) accept:

Option	Default	Description
`api_key`	required	Bearer key from `lore provision` or `lore keys create`.
`base_url`	`http://localhost:8080`	The Lore server URL.
`timeout`	~30s	An `httpx.Timeout` or a float of seconds.
`headers`	—	Extra headers sent on every request.
`transport`	—	A custom `httpx` transport (proxy, tests).

Errors

Every failure is a LoreError subclass. Catch the one case you handle specially by its class, and let a LoreError branch cover the rest:

from loregpt import LoreError, MinSeqOutOfRangeError

try:
    pack = lore.pack(run_id=run.run_id, query="…", min_seq=result.seq)
except MinSeqOutOfRangeError:
    # the run hasn't reached that seq — re-check the seq you're passing
    ...
except LoreError as err:
    # unauthorized · not_found · model_mismatch · connection · … — err.code tells you which
    print(err.code)

The full code → class map is in the API reference.

For the exhaustive method and type reference, see the package on PyPI.

Install

Usage

Async

Client options

Errors

On this page