Python SDK

pip install locusgraph-client
 
# With LangChain support:
pip install locusgraph-client[langchain]

from locusgraph_client import LocusGraphClient
 
client = LocusGraphClient(
    server_url="https://api.locusgraph.com",  # optional, default
    agent_secret="your-agent-secret",
    graph_id="default",  # optional default graph
)

response = client.store_event({
    "graph_id": "default",
    "event_kind": "fact",
    "source": "onboarding-flow",
    "context_id": "user-preferences",
    "payload": "User prefers dark mode and weekly email digests.",
    "reinforces": ["ctx-abc123"],
    "extends": [],
    "contradicts": [],
    "related_to": ["ctx-def456"],
    "timestamp": "2025-01-15T10:30:00Z",
})
 
# StoreEventResponse
# response.event_id   -> "evt-789"
# response.context_id -> "user-preferences"
# response.status     -> "stored"

result = client.retrieve_memories(
    query="What are the user notification preferences?",
    graph_id="default",
    limit=5,
    context_ids=["user-preferences"],
    context_types=["fact", "decision"],
)
 
# ContextResult
# result.memories -> [
#   { context_id: "user-preferences", content: "...", score: 0.92, ... }
# ]

try:
    context = client.get_context(
        context_id="user-preferences",
        graph_id="default",
    )
    # GetContextResponse
    # context.context_id   -> "user-preferences"
    # context.context_type -> "fact"
    # context.content      -> "User prefers dark mode..."
except RuntimeError as e:
    print(e)  # "Context not found"

types = client.list_context_types(
    graph_id="default",
    page=0,
    page_size=100,
)
# ContextTypesResponse
# types.context_types -> ["fact", "action", "decision", ...]

facts = client.list_contexts_by_type(
    context_type="fact",
    graph_id="default",
    page=0,
    page_size=50,
)
# ContextListResponse
# facts.contexts -> [{ context_id: "...", content: "...", ... }]

results = client.search_contexts(
    query="preferences",
    graph_id="default",
    limit=10,
)
# ContextSearchResponse
# results.contexts -> [...]

relationships = client.get_context_relationships(
    context_type="fact",
    context_name="user-preferences",
    graph_id="default",
)
# ContextRelationshipsResponse
# relationships.reinforced_by -> [...]
# relationships.extended_by   -> [...]
# relationships.contradicted_by -> [...]

insight = client.generate_insights(
    task="Summarize user preferences and suggest personalization strategies.",
    graph_id="default",
    locus_query="user preferences and settings",
    limit=10,
    context_ids=["user-preferences"],
    context_types=["fact", "decision"],
)
 
# InsightResult
# insight.insight    -> "Based on stored knowledge, the user prefers..."
# insight.sources    -> ["ctx-abc123", "ctx-def456"]
# insight.confidence -> 0.89