NeuroWeave API¶
The main entry point for library consumers.
NeuroWeave¶
NeuroWeave ¶
The public API for NeuroWeave — knowledge graph memory for AI agents.
NeuroWeave manages the full lifecycle: extraction pipeline, graph store, query engines, event bus, and optional visualization server. Agents interact through three main methods:
process(message)— Extract knowledge from a message, update the graph.query(...)— Query the graph (structured or natural language).get_context(message)— Process + query in one call (most common).
Usage
Programmatic construction¶
nw = NeuroWeave(llm_provider="mock") await nw.start() context = await nw.get_context("My wife Lena loves sushi") await nw.stop()
Context manager (recommended)¶
async with NeuroWeave(llm_provider="mock") as nw: context = await nw.get_context("My wife Lena loves sushi")
From config file¶
async with NeuroWeave.from_config("config/default.yaml") as nw: ...
__init__ ¶
__init__(*, llm_provider: str | None = None, llm_model: str | None = None, llm_api_key: str | None = None, enable_visualization: bool = False, server_host: str | None = None, server_port: int | None = None, log_level: str | None = None, log_format: str | None = None) -> None
from_config
classmethod
¶
Create a NeuroWeave instance from a YAML config file.
The YAML file is loaded first, then .env and NEUROWEAVE_*
environment variables are overlaid (env vars win).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to the YAML configuration file. |
required |
enable_visualization
|
bool
|
Whether to start the graph visualizer. |
False
|
Returns:
| Type | Description |
|---|---|
NeuroWeave
|
NeuroWeave instance (not yet started — call start() or use as context manager). |
start
async
¶
Initialize all components and optionally start the visualization server.
This must be called before using process/query/get_context. Prefer using the async context manager instead of calling start/stop manually.
process
async
¶
Extract knowledge from a message and update the graph.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
A user's conversational message. |
required |
Returns:
| Type | Description |
|---|---|
ProcessResult
|
ProcessResult with extraction details and graph delta. |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If NeuroWeave hasn't been started. |
query
async
¶
query(text_or_entities: str | list[str] | None = None, *, relations: list[str] | None = None, min_confidence: float = 0.0, max_hops: int = 1) -> QueryResult
Query the knowledge graph.
Auto-detects the query mode: - String input → Natural language query (LLM translates to graph query). - List input → Structured query (entity names passed directly). - None → Whole-graph query.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
text_or_entities
|
str | list[str] | None
|
Natural language question (str), entity names (list), or None for whole-graph. |
None
|
relations
|
list[str] | None
|
Relation types to filter on (structured mode only). |
None
|
min_confidence
|
float
|
Minimum edge confidence (structured mode only). |
0.0
|
max_hops
|
int
|
Hop traversal depth (structured mode only). |
1
|
Returns:
| Type | Description |
|---|---|
QueryResult
|
QueryResult with matching nodes and edges. |
get_context
async
¶
Process a message AND query for relevant context — in one call.
This is the most common operation for agent integration: 1. Extract entities/relations from the message and update the graph. 2. Use the NL query planner to find relevant existing knowledge. 3. Return both results together.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
A user's conversational message. |
required |
Returns:
| Type | Description |
|---|---|
ContextResult
|
ContextResult with extraction details and relevant graph context. |
subscribe ¶
Register an async callback to receive graph mutation events.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
handler
|
EventHandler
|
Async function that takes a GraphEvent. |
required |
event_types
|
set[GraphEventType] | None
|
Set of event types to filter on. None = all events. |
None
|
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If NeuroWeave hasn't been started. |
unsubscribe ¶
Remove a previously registered event handler.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
handler
|
EventHandler
|
The same function object passed to subscribe(). |
required |
create_visualization_app ¶
Create a FastAPI app for the graph visualizer.
Use this if you want to mount the visualization alongside your own FastAPI routes instead of running it as a standalone server.
Returns:
| Type | Description |
|---|---|
Any
|
FastAPI application instance. |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If NeuroWeave hasn't been started. |
ProcessResult¶
ProcessResult
dataclass
¶
Result of processing a single message through the extraction pipeline.
Attributes:
| Name | Type | Description |
|---|---|---|
extraction |
ExtractionResult
|
Raw extraction result (entities, relations, timing). |
nodes_added |
int
|
Number of new nodes created in the graph. |
edges_added |
int
|
Number of new edges created in the graph. |
edges_skipped |
int
|
Number of edges skipped (unknown entities, etc.). |
ContextResult¶
ContextResult
dataclass
¶
Combined result of processing a message AND querying relevant context.
This is the main return type for get_context() — the most common
operation in agent integration.
Attributes:
| Name | Type | Description |
|---|---|---|
process |
ProcessResult
|
What was extracted from this message. |
relevant |
QueryResult
|
Knowledge graph context relevant to this message. |
plan |
QueryPlan | None
|
The NL query plan used (for debugging/transparency). |