knowledge_graph
FalkorDB-backed knowledge graph with hybrid vector+graph retrieval.
- class knowledge_graph.KnowledgeGraphManager(redis_client, openrouter, embedding_model='google/gemini-embedding-001', admin_user_ids=None)[source]
Bases:
objectManages the FalkorDB knowledge graph for entity/relationship CRUD and hybrid retrieval.
- Parameters:
redis_client (aioredis.Redis)
openrouter (OpenRouterClient)
embedding_model (str)
- GRAPH_NAME = 'knowledge'
- __init__(redis_client, openrouter, embedding_model='google/gemini-embedding-001', admin_user_ids=None)[source]
Initialize the instance.
- Parameters:
redis_client (
Redis) – Redis connection client.openrouter (
OpenRouterClient) – The openrouter value.embedding_model (
str) – The embedding model value.admin_user_ids (
set[str] |None) – The admin user ids value.
- Return type:
None
- async ensure_indexes()[source]
Create vector + range indexes for every entity label.
This operation is idempotent.
- Return type:
- async add_entity(name, entity_type, description, category='general', scope_id='_', created_by='unknown', pinned=False, metadata='{}', user_id='000000000000', embedding=None)[source]
Create or update an entity.
Returns
{"name": ..., "uuid": ...}.
- async update_entity_description(name, entity_type, new_description, category=None, scope_id=None)[source]
Update an entity’s description and re-embed.
- async edit_entity(uuid, description=None, append_text=None, pinned=None, category=None, metadata_updates=None)[source]
Selectively update fields on an existing entity.
Looks up by uuid. Only the provided fields are changed; everything else is preserved.
description replaces the text entirely. append_text is concatenated to the existing description. (Mutually exclusive – caller must pick one.)
metadata_updates is shallow-merged into the existing metadata JSON (new keys added, existing overwritten, unmentioned preserved).
Returns the full updated entity dict via
get_entity(), orNoneif the UUID was not found.
- async delete_entity(name, entity_type, category, scope_id='_')[source]
Delete the specified entity.
- async delete_entity_by_uuid(uuid)[source]
Delete an entity by UUID (detach-deletes all relationships).
- async pin_entity(name, entity_type, pinned=True, category=None, scope_id=None)[source]
Set or clear the pinned flag on an entity.
When category and/or scope_id are provided, only entities matching those filters are updated. This avoids pinning the wrong entity when the same name exists in multiple scopes.
- async get_entity(name='', entity_type=None, category=None, scope_id=None, uuid=None)[source]
Fetch an entity with its immediate connections.
Can look up by name or by uuid.
- async inspect_entity(name='', uuid=None, max_depth=2, neighbor_limit=50)[source]
Deep inspection of an entity and its full neighborhood.
Returns the entity’s properties plus all outgoing and incoming relationships (up to max_depth hops), with each neighbor’s core properties included.
- async list_entities(entity_type=None, category=None, scope_id=None, limit=50)[source]
List entities with optional filtering.
- async add_relationship(source_uuid, target_uuid, relation_type, weight=0.5, description='', evidence='')[source]
Create or reinforce a relationship between two entities identified by UUID.
The edge inherits
priority = min(source, target)and thecategory/scope_idfrom the lower-priority endpoint. Cross-category edges are fully supported.
- async delete_relationship(source_uuid, target_uuid, relation_type)[source]
Delete the specified relationship.
- async list_relationships(entity_uuid=None, relation_type=None, category=None, limit=50, order_by=True, timeout=None)[source]
List relationships.
- async resolve_entity_cross_category(name, entity_type)[source]
Find an entity by name across all categories.
Used for cross-category linking.
- async retrieve_context(query, query_embedding=None, user_ids=None, channel_id=None, guild_id=None, max_hops=2, max_per_user=20, max_channel=15, max_guild=15, max_general=30, seed_top_k=5000)[source]