Python SDK
The official Python client for LocusGraph. Use it to wire your Python agent, LangChain pipeline, or backend service into Structured Agent Knowledge: store typed events, retrieve validated knowledge, and generate insights from one client.
Installation
pip install locusgraph-client
# With LangChain support:
pip install locusgraph-client[langchain]Configuration
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
)Set LOCUSGRAPH_SERVER_URL and LOCUSGRAPH_AGENT_SECRET as environment variables to avoid hardcoding credentials. The client reads these automatically when no explicit values are provided.
Store Event
Add knowledge to LocusGraph with store_event. The admission pipeline turns each event into a locus in your structured agent knowledge 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"Retrieve Knowledge
Run semantic search across your structured agent knowledge with retrieve_memories.
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, ... }
# ]Get Context
Fetch a single context by ID. Raises RuntimeError("Context not found") on 404.
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"List Contexts
Browse, filter, and search contexts in your LocusGraph workspace.
List context types
types = client.list_context_types(
graph_id="default",
page=0,
page_size=100,
)
# ContextTypesResponse
# types.context_types -> ["fact", "action", "decision", ...]List contexts by type
facts = client.list_contexts_by_type(
context_type="fact",
graph_id="default",
page=0,
page_size=50,
)
# ContextListResponse
# facts.contexts -> [{ context_id: "...", content: "...", ... }]Search contexts
results = client.search_contexts(
query="preferences",
graph_id="default",
limit=10,
)
# ContextSearchResponse
# results.contexts -> [...]Get Context Relationships
Explore how contexts connect within your structured agent knowledge graph.
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 -> [...]Generate Insights
Reason over your structured agent knowledge to produce synthesized answers.
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.89Environment Variables
| Variable | Description |
|---|---|
LOCUSGRAPH_SERVER_URL | API server URL (default: https://api.locusgraph.com) |
LOCUSGRAPH_AGENT_SECRET | Your agent secret key |