ooai-persistence¶

Typed persistence helpers for LangGraph-based OOAI applications.

Start here¶

The usual entrypoints are:

memory_settings() for tests and no-infra runs
sqlite_settings(path) for one-file local persistence
postgres_settings(...) for the real async Postgres path

from ooai_persistence import memory_settings, postgres_settings, sqlite_settings

memory = memory_settings()
sqlite = sqlite_settings(".ooai/persistence/dev.sqlite3")
postgres = postgres_settings(database="ooai_persistence")

If you do not want to touch settings at all, open the bundle directly:

from ooai_persistence import open_postgres_persistence

async with open_postgres_persistence(database="ooai_persistence") as persistence:
    await persistence.store.aput(("profiles", "demo"), "name", {"value": "Will"})

If you only want the store, you can open just that resource:

from ooai_persistence import open_postgres_store

async with open_postgres_store(database="ooai_persistence") as store:
    await store.aput(("profiles", "demo"), "name", {"value": "Will"})

from ooai_persistence import open_sync_persistence, sqlite_settings

settings = sqlite_settings(".ooai/persistence/dev.sqlite3")

with open_sync_persistence(settings) as persistence:
    checkpointer = persistence.checkpointer
    store = persistence.store
    graph_cache = persistence.graph_cache

Pragmatic patterns¶

The most useful entrypoints are:

open_sync_persistence(...) and open_persistence(...) when you want raw store/checkpointer access
open_sync_memory_persistence(...), open_sqlite_persistence(...), and open_postgres_persistence(...) when you want that access without building settings first
open_sync_store(...) and open_store(...) when you only want the long-term store
open_sync_graph(...) and open_graph(...) when you want a compiled LangGraph plus managed persistence
bind_graph_with_persistence(...) when the graph is already compiled somewhere else

Install¶

pdm install -G :all

Backend extras are available for Postgres, SQLite, Redis, MongoDB, LangSmith, and docs:

pdm add "ooai-persistence[postgres]"
pdm add "ooai-persistence[sqlite]"

Configuration¶

Use AppSettings directly, or load settings from .env with the OOAI_PERSISTENCE_ prefix.

from typing import TypedDict

from langgraph.graph import END, START, StateGraph
from ooai_persistence import open_graph, postgres_settings


class State(TypedDict):
    question: str
    answer: str


def respond(state: State) -> State:
    return {"answer": f"Echo: {state['question']}"}


graph = StateGraph(State)
graph.add_node("respond", respond)
graph.add_edge(START, "respond")
graph.add_edge("respond", END)

settings = postgres_settings(database="ooai_persistence")

async with open_graph(graph, settings) as runtime:
    await runtime.persistence.store.aput(("profiles", "demo"), "name", {"value": "Will"})
    result = await runtime.graph.ainvoke(
        {"question": "hello", "answer": ""},
        config={"configurable": {"thread_id": "demo-thread"}},
    )

Checkpointed graph runs need a runnable config such as {"configurable": {"thread_id": "demo-thread"}}.

LangSmith settings read standard LANGSMITH_* variables:

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=...
LANGSMITH_PROJECT=ooai

Local Infrastructure¶

make bootstrap
make infra-up
make infra-test-postgres
make infra-down

See infra/README.md for Docker Compose details.

CLI Smoke Checks¶

ooai-persistence doctor --backend postgres --json
ooai-persistence smoke --backend memory
ooai-persistence smoke --backend sqlite --sqlite-path .ooai/persistence/smoke.sqlite3
ooai-persistence smoke --backend postgres --async

The Postgres smoke path opens async LangGraph checkpointer and store resources, runs setup, and verifies real round trips.

Existing compiled graphs¶

from ooai_persistence import bind_graph_with_persistence, memory_settings, open_sync_persistence

compiled = graph.compile()

with open_sync_persistence(memory_settings()) as bundle:
    persistent_graph = bind_graph_with_persistence(compiled, bundle)
    result = persistent_graph.invoke(
        {"question": "hello", "answer": ""},
        config={"configurable": {"thread_id": "demo-thread"}},
    )

API Reference¶

`ooai_persistence`	Top-level package for `ooai_persistence`.
`ooai_persistence.settings`	Settings models for `ooai_persistence`.
`ooai_persistence.context`	Context managers for persistence resources.
`ooai_persistence.graphs`	Helpers for wiring persistence bundles into LangGraph graphs.
`ooai_persistence.resources`	Convenience resource-loading helpers for `ooai_persistence`.
`ooai_persistence.registry`	Backend resolution helpers for `ooai_persistence`.
`ooai_persistence.serde.registry`	Msgpack allowlist registry helpers.