Zum Inhalt

Overview

package wittgenstein_kg_client

wittgenstein-kg-client — knowledge graph client with read/write primitives and RAG search.

Classes

  • KnowledgeGraphClient — KG client with RAG (pgvector) search or ILIKE fallback.

  • Fact — A generic subject-relation-object fact read back from any node/edge type.

  • FilterPattern — A recommended SQL snippet for filtering or aggregating a table.

  • Gotcha — A data quality warning associated with a database table.

  • Indicator — A domain metric/KPI node from the knowledge graph.

  • KGSearchResult — Aggregated result of a KG keyword search across all node types.

  • Edge — A directed knowledge graph edge between two nodes.

  • Node — A knowledge graph node to be written to the DB.

Functions

  • extract_keywords — Extract meaningful lowercase words from a question for ILIKE pattern matching.

  • ensure_schema — Create the KG tables (and pgvector extension) if they don't exist yet.

  • cypher_properties — Render a dict as a Cypher property map literal: {key: value, ...}.

  • cypher_str — Escape a string value for use in a Cypher query.

  • sql_json_literal — Serialize a dict to a SQL string literal containing JSON.

  • sql_literal — Escape a string value for use as a SQL literal (single-quoted).

wittgenstein_kg_client.KnowledgeGraphClient

mkapi_definition_mkapi class KnowledgeGraphClient(pg_dsn: str, embedding_client: Any | None = None, extractor: Any | None = None)

KG client with RAG (pgvector) search or ILIKE fallback.

Parameters

  • pg_dsn : str — psycopg2-compatible DSN, e.g. 'postgresql://user:pass@host:port/dbname'

  • embedding_client : Any | None — object with .query(text) -> list[float] (e.g. wittgenstein_embeddings.EmbeddingClient). When provided, search() uses pgvector cosine similarity (RAG). When None, falls back to ILIKE keywords.

  • extractor : Any | None — optional object with .extract(text, schema) -> list[str] (e.g. a caller-written adapter around GLiNER/GLiNER2 or any other schema-guided extraction model). Only used by the ILIKE path, and only when search(..., schema=...) also passes a schema — this lib never imports gliner/gliner2 itself and takes no position on which extraction package/model to use.

Methods

  • search — Search the KG for gotchas, filter patterns, and indicators.

  • search_gotchas — Return gotcha nodes matching keywords (ILIKE).

  • search_filter_patterns — Return filter pattern nodes matching keywords (ILIKE).

  • search_indicators — Return indicator nodes matching keywords (ILIKE).

  • find_facts — Generic keyword search over any node/edge type in a graph.

  • all_facts — Return every edge in a graph as subject-relation-object facts (for graph views).

  • create_graph — Return the id of the graph named name, creating it if needed.

  • add_node — Upsert a node by (graph_id, label): merges properties if it already exists.

  • add_edge — Insert an edge between two nodes looked up by label.

wittgenstein_kg_client.KnowledgeGraphClient.search

mkapi_definition_mkapi method KnowledgeGraphClient.search(graph_name: str, question: str, gotcha_limit: int = 6, pattern_limit: int = 5, indicator_limit: int = 5, schema: Any | None = None) → KGSearchResult

Search the KG for gotchas, filter patterns, and indicators.

Uses RAG (pgvector) when an embedding_client was provided at construction; falls back to ILIKE keyword matching otherwise. schema only affects the ILIKE path's keyword extraction — see extractor.

wittgenstein_kg_client.KnowledgeGraphClient.search_gotchas

mkapi_definition_mkapi method KnowledgeGraphClient.search_gotchas(graph_name: str, keywords: list[str], limit: int = 6) → list[Gotcha]

Return gotcha nodes matching keywords (ILIKE).

wittgenstein_kg_client.KnowledgeGraphClient.search_filter_patterns

mkapi_definition_mkapi method KnowledgeGraphClient.search_filter_patterns(graph_name: str, keywords: list[str], limit: int = 5) → list[FilterPattern]

Return filter pattern nodes matching keywords (ILIKE).

wittgenstein_kg_client.KnowledgeGraphClient.search_indicators

mkapi_definition_mkapi method KnowledgeGraphClient.search_indicators(graph_name: str, keywords: list[str], limit: int = 5) → list[Indicator]

Return indicator nodes matching keywords (ILIKE).

wittgenstein_kg_client.KnowledgeGraphClient.find_facts

mkapi_definition_mkapi method KnowledgeGraphClient.find_facts(graph_id: str, question: str, limit: int = 20) → list[Fact]

Generic keyword search over any node/edge type in a graph.

Unlike search() (which only looks at the domain-specific node types), this matches any subject/relation/object — the right query for graphs built by generic write-side callers like add_node/add_edge.

wittgenstein_kg_client.KnowledgeGraphClient.all_facts

mkapi_definition_mkapi method KnowledgeGraphClient.all_facts(graph_id: str, limit: int = 500) → list[Fact]

Return every edge in a graph as subject-relation-object facts (for graph views).

wittgenstein_kg_client.KnowledgeGraphClient.create_graph

mkapi_definition_mkapi method KnowledgeGraphClient.create_graph(name: str) → str

Return the id of the graph named name, creating it if needed.

wittgenstein_kg_client.KnowledgeGraphClient.add_node

mkapi_definition_mkapi method KnowledgeGraphClient.add_node(graph_id: str, node: Node) → str

Upsert a node by (graph_id, label): merges properties if it already exists.

wittgenstein_kg_client.KnowledgeGraphClient.add_edge

mkapi_definition_mkapi method KnowledgeGraphClient.add_edge(graph_id: str, edge: Edge) → str | None

Insert an edge between two nodes looked up by label.

Returns None (and logs a warning) without inserting anything if either endpoint node does not exist yet in this graph.

wittgenstein_kg_client.extract_keywords

mkapi_definition_mkapi extract_keywords(question: str, max_keywords: int = 12) → list[str]

Extract meaningful lowercase words from a question for ILIKE pattern matching.

Filters out stopwords and words shorter than 3 characters.

Parameters

  • question : str — natural-language question or search term.

  • max_keywords : int — maximum number of keywords to return (avoids huge SQL lists).

Returns

  • list[str] — list of lowercase keyword strings, at most max_keywords items.

wittgenstein_kg_client.Fact

mkapi_definition_mkapi dataclass Fact(subject: str, relation: str, object: str)

A generic subject-relation-object fact read back from any node/edge type.

wittgenstein_kg_client.FilterPattern

mkapi_definition_mkapi dataclass FilterPattern(table_name: str, pattern_label: str, sql_snippet: str)

A recommended SQL snippet for filtering or aggregating a table.

wittgenstein_kg_client.Gotcha

mkapi_definition_mkapi dataclass Gotcha(table_name: str, warning: str)

A data quality warning associated with a database table.

wittgenstein_kg_client.Indicator

mkapi_definition_mkapi dataclass Indicator(node_label: str, acronym: str | None, definition: str | None, category: str | None)

A domain metric/KPI node from the knowledge graph.

wittgenstein_kg_client.KGSearchResult

mkapi_definition_mkapi dataclass KGSearchResult(gotchas: list[Gotcha], patterns: list[FilterPattern], indicators: list[Indicator])

Aggregated result of a KG keyword search across all node types.

wittgenstein_kg_client.KGSearchResult.is_empty

mkapi_definition_mkapi property KGSearchResult.is_empty: bool

wittgenstein_kg_client.ensure_schema

mkapi_definition_mkapi ensure_schema(pg_dsn: str) → None

Create the KG tables (and pgvector extension) if they don't exist yet.

Idempotent — safe to call on every app startup. Only needed for standalone consumers; the platform's agent_platform database manages this schema via Alembic instead (see repository_structure_reference).

Also creates the HNSW index used by the RAG similarity search path (see schema.sql). Building that index for the first time against a table that already holds a large number of embedded rows can be slow/memory-heavy — see the comment above the index in schema.sql before calling this against a pre-populated database.

wittgenstein_kg_client.cypher_properties

mkapi_definition_mkapi cypher_properties(props: dict) → str

Render a dict as a Cypher property map literal: {key: value, ...}.

wittgenstein_kg_client.cypher_str

mkapi_definition_mkapi cypher_str(value: str) → str

Escape a string value for use in a Cypher query.

wittgenstein_kg_client.sql_json_literal

mkapi_definition_mkapi sql_json_literal(obj: dict) → str

Serialize a dict to a SQL string literal containing JSON.

wittgenstein_kg_client.sql_literal

mkapi_definition_mkapi sql_literal(value: str) → str

Escape a string value for use as a SQL literal (single-quoted).

wittgenstein_kg_client.Edge

mkapi_definition_mkapi dataclass Edge(source: str, target: str, edge_type: str, properties: dict = field(default_factory=dict))

A directed knowledge graph edge between two nodes.

wittgenstein_kg_client.Node

mkapi_definition_mkapi dataclass Node(semantic_id: str, node_type: str, label: str, properties: dict = field(default_factory=dict), tags: list[str] = field(default_factory=list))

A knowledge graph node to be written to the DB.