Package com.tnsai.tools.knowledge

Class KnowledgeTools

java.lang.Object

com.tnsai.tools.knowledge.KnowledgeTools

public class KnowledgeTools
extends Object

Function-shape knowledge-graph tools — in-memory NER + triple store with regex-based pattern extraction. Replaces the legacy KnowledgeGraphTool (single dispatched tool with 10 ops). Migrates the four most-useful operations into typed @Tool methods. Persistence (the legacy stored ~/.tnsai/knowledge-graph) is intentionally dropped — callers who need durability should pair this with the database tools.

Method	Purpose	Idempotent
kgExtractEntities(java.lang.String, java.util.List<java.lang.String>)	Regex NER (PERSON / ORG / LOCATION / DATE / EMAIL / URL / TECHNOLOGY)	true
kgExtractRelations(java.lang.String)	Regex relation extraction (works_for / founded / located_in / acquired / uses / is_a / part_of)	true
kgAddTriple(java.lang.String, java.lang.String, java.lang.String)	Store a (subject, predicate, object) fact	true (set semantics)
kgQuery(java.lang.String, java.lang.String, java.lang.String)	Query stored triples by any combination of subject / predicate / object	true

Pure-JDK / no auth / no network. Each instance keeps its own CopyOnWriteArrayList (read-heavy + low-write). Live instances are the GraphRAG backend: when tnsai-intelligence is on the classpath, @Search(strategy = GRAPH) reads liveTriples() through the knowledge-tools GraphStoreProvider. Instance bags are not shared with each other — BuiltInTool.instantiate() still returns a fresh store — but every live bag is visible to graph retrieval.

Since:

0.5.7 (Phase 2 batch 22 — built-in tool migration to function shape, see #188)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	KnowledgeTools.Entity	A discovered or stored entity match.
static final record	KnowledgeTools.Triple	A subject-predicate-object triple.

Constructor Summary

Constructors

Constructor	Description
KnowledgeTools()

Method Summary

Modifier and Type	Method	Description
int	kgAddTriple(String subject, String predicate, String object)
List<KnowledgeTools.Entity>	kgExtractEntities(String text, List<String> types)
List<KnowledgeTools.Triple>	kgExtractRelations(String text)
List<KnowledgeTools.Triple>	kgQuery(String subject, String predicate, String object)
static List<KnowledgeTools.Triple>	liveTriples()	Deduplicated snapshot of triples held by every live KnowledgeTools instance.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

KnowledgeTools

public KnowledgeTools()

Method Details

liveTriples

public static List<KnowledgeTools.Triple> liveTriples()

Deduplicated snapshot of triples held by every live KnowledgeTools instance.

Graph retrieval reads this on every retrieve, so a kg_add_triple that lands after the Role binding was built is still visible. Instances do not share a bag: two tool objects keep separate lists, and this method unions them.

Returns:

immutable snapshot, never null

Since:

0.14.0

kgExtractEntities

@Tool(name="kg_extract_entities",
      description="Extract named entities (PERSON / ORGANIZATION / DATE / EMAIL / URL / TECHNOLOGY) from {text} using regex patterns. Optional {types} narrows to a subset (case-insensitive). Returns a list of Entity records.",
      keywords={"knowledge","ner","entities","extract","person","organization"},
      idempotent=true)
public List<KnowledgeTools.Entity> kgExtractEntities(@ToolParam(description="Source text to scan")
 String text,
 @ToolParam(description="Optional entity-type filter (empty list \u2192 all types)",required=false)
 List<String> types)

kgExtractRelations

@Tool(name="kg_extract_relations",
      description="Extract (subject, predicate, object) relations from {text} using regex patterns. Predicates: works_for / founded / located_in / acquired / uses / is_a / part_of. Returns a list of Triple records.",
      keywords={"knowledge","relation","extract","triple","subject","predicate"},
      idempotent=true)
public List<KnowledgeTools.Triple> kgExtractRelations(@ToolParam(description="Source text to scan")
 String text)

kgAddTriple

@Tool(name="kg_add_triple",
      description="Store a (subject, predicate, object) triple in this instance\'s in-memory bag. Live bags are the GraphRAG backend when tnsai-intelligence is on the classpath (@Search GRAPH, source knowledge-tools). Set semantics \u2014 duplicate adds are no-ops. Returns the count of triples in this instance after the add.",
      keywords={"knowledge","add","triple","store","fact"},
      idempotent=true)
public int kgAddTriple(@ToolParam(description="Subject (e.g. \"apple\")")
 String subject,
 @ToolParam(description="Predicate (e.g. \"is_a\")")
 String predicate,
 @ToolParam(description="Object (e.g. \"technology_company\")")
 String object)

kgQuery

@Tool(name="kg_query",
      description="Query the in-memory knowledge graph by any combination of {subject}, {predicate}, and {object}. Each filter is optional \u2014 leave blank to match anything. Returns the list of matching Triple records.",
      keywords={"knowledge","query","graph","triple","search"},
      idempotent=true)
public List<KnowledgeTools.Triple> kgQuery(@ToolParam(description="Optional subject filter (case-insensitive substring match)",required=false,defaultValue="")
 String subject,
 @ToolParam(description="Optional predicate filter (case-insensitive substring match)",required=false,defaultValue="")
 String predicate,
 @ToolParam(description="Optional object filter (case-insensitive substring match)",required=false,defaultValue="")
 String object)