Skip to content

client

module wittgenstein_kg_client.client

KnowledgeGraphClient — queries on knowledge_graphs / nodes / edges tables.

Supports RAG search (pgvector cosine similarity) when an embedding_client is provided; falls back to ILIKE keyword search otherwise.

Node types queried

  • table node → source for gotchas and filter patterns (via edges)
  • gotcha node → data quality warnings
  • filter-pattern node → SQL snippets
  • indicator node → KPI/metric definitions

Write side (create_graph/add_node/add_edge) targets the same tables and is domain-agnostic — any node_type/edge_type is accepted.

Classes

wittgenstein_kg_client.client.KnowledgeGraphClient

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.client.KnowledgeGraphClient.search

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.client.KnowledgeGraphClient.search_gotchas

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

Return gotcha nodes matching keywords (ILIKE).

wittgenstein_kg_client.client.KnowledgeGraphClient.search_filter_patterns

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.client.KnowledgeGraphClient.search_indicators

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

Return indicator nodes matching keywords (ILIKE).

wittgenstein_kg_client.client.KnowledgeGraphClient.find_facts

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.client.KnowledgeGraphClient.all_facts

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.client.KnowledgeGraphClient.create_graph

method KnowledgeGraphClient.create_graph(name: str) → str

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

wittgenstein_kg_client.client.KnowledgeGraphClient.add_node

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.client.KnowledgeGraphClient.add_edge

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.