hyphal 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atharva Deshpande
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# hyphal
+
+**Turn your unstructured documents into something your agents can actually reason over.**
+
+Hand hyphal a pile of documents. It reads them once, builds an RDF ontology and a validated fact graph as it goes, and gives your agents a way to ask precise questions against everything it's read — instead of re-reading raw text every turn, or drowning in a context window that grows with your document count.
+
+```bash
+export ANTHROPIC_API_KEY=sk-...
+npx hyphal extract document1.txt document2.txt
+```
+
+Runs entirely on your infrastructure, on your own Anthropic key. No server, no hosted service, nothing leaves your machine. 
+
+---
+
+## What your agents get
+
+Not the documents. Not a data dump. Two things, both cheap to hand an agent on every call:
+
+- **A schema** — stable, versioned, safe to keep in context indefinitely — that tells the agent what's knowable about your document set.
+- **A query interface** — SPARQL, run locally against the extracted graph — the agent asks exactly what it needs and gets back exactly that, at effectively zero marginal cost per question, regardless of the size.
+
+
+## How it stays accurate as your document set grows
+
+Every new document is processed against the ontology's current serialized state, shown to the model as context — not extracted from scratch. Whatever the model proposes is diffed against exactly that snapshot, an exact structural comparison, not fuzzy or embedding-based. Anything it restates that already exists is dropped before it's ever written; only the genuine delta gets committed, as a new content-hashed version chained to the one before it.
+
+The same discipline applies to entities: before extracting facts from a new document, the model is shown a summary of what's already known, so "Acme" in document forty resolves to the same record "Acme Robotics Inc." created in document one — not a duplicate. Facts live in a separate namespace from the schema, so the two can never collide.
+
+Run two real documents through the same store and the effect is directly observable: the first contributes a substantial ontology delta, the second contributes noticeably less, because the concepts it needs mostly already exist. That shrinking delta is the mechanism working
+
+## Architecture
+
+```mermaid
+flowchart TD
+    A[Unstructured documents] --> B[Render + diff loop]
+    B --> C[Ontology store]
+    B --> D[Facts store]
+    C --> E[Query layer — SPARQL via Comunica]
+    D --> E
+    E --> F[Your agents]
+```
+
+## What gets exposed to your agents
+
+Three functions, deliberately small in count — this is the whole tool surface an agent framework needs to wrap:
+
+- **`toTurtle()`** — the current schema, serialized. Cheap enough to include as context on every single call, so the agent always knows what's askable before it asks anything.
+- **`queryGraph(sparql)`** — the agent writes its own SPARQL, informed by the schema above, and gets back exactly the matching rows. Runs locally, no LLM in the path, effectively free per call.
+- **`searchEntities(name)`** — resolves a name the agent knows ("Acme") to the exact identifier it doesn't (`cd:acme_robotics_inc`), so the query above can be precise instead of guessed.
+
+An agent gets the schema once per turn, calls `searchEntities` when it needs an identifier, and `queryGraph` when it needs a fact — nothing more ever needs to enter its context.
+
+
+## For engineers looking at the code
+
+The entire reuse-not-duplicate mechanism lives in dependency-free function: `complementInserts` in `src/diff.ts` — an exact subject/predicate/object(+datatype) key comparison against the snapshot the model was shown, roughly twenty lines. `test/diff.test.ts` proves it deterministically, no API key required, if you'd rather verify the claim above than take it on faith.
+
+Querying runs on Comunica against N3-backed RDF stores, entirely locally — real SPARQL, real joins, no LLM anywhere in the query path. Only the extraction step costs anything. Entity resolution (`searchEntities`) is a plain label substring match today, not embeddings — deliberately simple, resolves a name an agent knows to an IRI it doesn't, ahead of a precise query.
+
+This is an early, honest-scope build: single process, sequential, in-memory per run, no persistence across invocations yet, no document-update or retraction handling. Each is a deliberate next step, not an oversight — the priority so far has been proving the core mechanism before hardening what's around it. Issues and PRs welcome, especially on persistence and entity resolution.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,60 @@
+import { readFile } from "node:fs/promises";
+import { OntologyStore } from "./store.js";
+import { FactsStore } from "./factStore.js";
+import { evolveOntology } from "./ontology.js";
+import { extractFacts } from "./facts.js";
+const DEFAULT_PREFIXES = {
+    ex: "https://example.org/ontology#",
+    cd: "https://example.org/facts#",
+    rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+    rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+    xsd: "http://www.w3.org/2001/XMLSchema#",
+};
+function parseArgs(argv) {
+    const args = [...argv];
+    let apiKey = process.env.ANTHROPIC_API_KEY;
+    const files = [];
+    while (args.length) {
+        const arg = args.shift();
+        if (arg === "--api-key") {
+            apiKey = args.shift();
+        }
+        else if (arg === "extract") {
+            // command word, ignore
+        }
+        else {
+            files.push(arg);
+        }
+    }
+    return { apiKey, files };
+}
+async function main() {
+    const { apiKey, files } = parseArgs(process.argv.slice(2));
+    if (!apiKey) {
+        console.error("Error: no API key found. Set ANTHROPIC_API_KEY in your environment, or pass --api-key sk-...\n" +
+            "This tool never ships or stores a key of its own — it only uses yours, for this run.");
+        process.exit(1);
+    }
+    if (files.length === 0) {
+        console.error("Usage: hyphal extract <file.txt> [file2.txt ...]");
+        process.exit(1);
+    }
+    const ontologyStore = new OntologyStore(DEFAULT_PREFIXES);
+    const factsStore = new FactsStore(DEFAULT_PREFIXES);
+    for (const file of files) {
+        const text = await readFile(file, "utf-8");
+        console.error(`\n--- Processing ${file} ---`);
+        const ontologyResult = await evolveOntology(ontologyStore, text, apiKey);
+        console.error(`Ontology: +${ontologyResult.added.length} new triple(s), version ${ontologyResult.version.hash} (parent: ${ontologyResult.version.parentHash ?? "none"})`);
+        const factsResult = await extractFacts(ontologyStore, factsStore, text, apiKey);
+        console.error(`Facts: +${factsResult.facts.length} new triple(s) (total: ${factsStore.size})`);
+    }
+    console.log("\n=== Final ontology (Turtle) ===");
+    console.log(await ontologyStore.toTurtle());
+    console.log("\n=== Final facts (Turtle) ===");
+    console.log(await factsStore.toTurtle());
+}
+main().catch((err) => {
+    console.error("Fatal error:", err.message ?? err);
+    process.exit(1);
+});

package/dist/diff.d.ts

@@ -0,0 +1,12 @@
+import type { Triple } from "./schemas.js";
+/**
+ * Return only the triples in `proposed` that are NOT already present in
+ * `snapshotKeys` — the exact ontology state that was shown to the LLM as
+ * context for this render call.
+ *
+ * This is the single most important function in the system: it's what lets
+ * the LLM freely restate existing schema (which it will do constantly,
+ * since it's reasoning over the whole snapshot) without that restatement
+ * being treated as new information.
+ */
+export declare function complementInserts(proposed: Triple[], snapshotKeys: Set<string>, prefixes: Record<string, string>): Triple[];

package/dist/diff.js

@@ -0,0 +1,24 @@
+import { tripleToQuad } from "./store.js";
+/**
+ * Return only the triples in `proposed` that are NOT already present in
+ * `snapshotKeys` — the exact ontology state that was shown to the LLM as
+ * context for this render call.
+ *
+ * This is the single most important function in the system: it's what lets
+ * the LLM freely restate existing schema (which it will do constantly,
+ * since it's reasoning over the whole snapshot) without that restatement
+ * being treated as new information.
+ */
+export function complementInserts(proposed, snapshotKeys, prefixes) {
+    const seenInThisBatch = new Set();
+    const result = [];
+    for (const triple of proposed) {
+        const quad = tripleToQuad(triple, prefixes);
+        const key = `${quad.subject.value}\u0000${quad.predicate.value}\u0000${quad.object.value}\u0000${quad.object.termType === "Literal" ? quad.object.datatype?.value ?? "" : ""}`;
+        if (!snapshotKeys.has(key) && !seenInThisBatch.has(key)) {
+            seenInThisBatch.add(key);
+            result.push(triple);
+        }
+    }
+    return result;
+}

package/dist/factStore.d.ts

@@ -0,0 +1,24 @@
+import { Store } from "n3";
+import type { Triple } from "./schemas.js";
+/**
+ * Store for extracted instance facts, kept separate from the ontology's
+ * own store. Adds getEntitySummary(), which lets extractFacts() show the
+ * LLM which entities already exist — the facts-side equivalent of showing
+ * the ontology snapshot for schema reuse.
+ */
+export declare class FactsStore {
+    readonly prefixes: Record<string, string>;
+    private store;
+    constructor(prefixes: Record<string, string>);
+    addNew(triples: Triple[]): Triple[];
+    toTurtle(): Promise<string>;
+    /**
+     * Compact text summary of known entities (IRI, type, label), shown to
+     * the LLM so it can reuse an existing entity's IRI instead of minting
+     * a duplicate under a different name.
+     */
+    getEntitySummary(): string;
+    /** Raw RDF/JS-compatible store, for Comunica SPARQL queries. */
+    get rdfSource(): Store;
+    get size(): number;
+}

package/dist/factStore.js

@@ -0,0 +1,88 @@
+import { Store, Writer } from "n3";
+import { tripleToQuad } from "./store.js";
+const RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
+const RDFS_LABEL = "http://www.w3.org/2000/01/rdf-schema#label";
+/** Turn a full IRI back into its prefixed form, e.g. "https://.../Company" -> "ex:Company". */
+function compactIri(iri, prefixes) {
+    for (const [prefix, namespace] of Object.entries(prefixes)) {
+        if (iri.startsWith(namespace)) {
+            return `${prefix}:${iri.slice(namespace.length)}`;
+        }
+    }
+    return `<${iri}>`; // fallback: full IRI, unrecognized namespace
+}
+function quadKey(subject, predicate, object) {
+    return `${subject}\u0000${predicate}\u0000${object}`;
+}
+/**
+ * Store for extracted instance facts, kept separate from the ontology's
+ * own store. Adds getEntitySummary(), which lets extractFacts() show the
+ * LLM which entities already exist — the facts-side equivalent of showing
+ * the ontology snapshot for schema reuse.
+ */
+export class FactsStore {
+    prefixes;
+    store = new Store();
+    constructor(prefixes) {
+        this.prefixes = prefixes;
+    }
+    addNew(triples) {
+        const existing = new Set(this.store
+            .getQuads(null, null, null, null)
+            .map((q) => quadKey(q.subject.value, q.predicate.value, q.object.value)));
+        const added = [];
+        for (const t of triples) {
+            const quad = tripleToQuad(t, this.prefixes);
+            const key = quadKey(quad.subject.value, quad.predicate.value, quad.object.value);
+            if (!existing.has(key)) {
+                this.store.addQuad(quad);
+                existing.add(key);
+                added.push(t);
+            }
+        }
+        return added;
+    }
+    toTurtle() {
+        return new Promise((resolve, reject) => {
+            const writer = new Writer({ prefixes: this.prefixes });
+            for (const quad of this.store.getQuads(null, null, null, null)) {
+                writer.addQuad(quad);
+            }
+            writer.end((err, result) => (err ? reject(err) : resolve(result)));
+        });
+    }
+    /**
+     * Compact text summary of known entities (IRI, type, label), shown to
+     * the LLM so it can reuse an existing entity's IRI instead of minting
+     * a duplicate under a different name.
+     */
+    getEntitySummary() {
+        const types = new Map(); // subject IRI -> type IRI
+        const labels = new Map(); // subject IRI -> label
+        for (const quad of this.store.getQuads(null, null, null, null)) {
+            if (quad.predicate.value === RDF_TYPE) {
+                types.set(quad.subject.value, quad.object.value);
+            }
+            else if (quad.predicate.value === RDFS_LABEL) {
+                labels.set(quad.subject.value, quad.object.value);
+            }
+        }
+        if (types.size === 0)
+            return "(no entities extracted yet)";
+        const lines = [];
+        for (const [subjectIri, typeIri] of types) {
+            const subject = compactIri(subjectIri, this.prefixes);
+            const type = compactIri(typeIri, this.prefixes);
+            const label = labels.get(subjectIri);
+            lines.push(label ? `${subject} (${type}, label: "${label}")` : `${subject} (${type})`);
+        }
+        return lines.join("\n");
+    }
+    /** Raw RDF/JS-compatible store, for Comunica SPARQL queries. */
+    get rdfSource() {
+        return this.store;
+    }
+    get size() {
+        return this.store.getQuads(null, null, null, null).length;
+    }
+}

package/dist/facts.d.ts

@@ -0,0 +1,12 @@
+import { OntologyStore } from "./store.js";
+import type { FactsStore } from "./factStore.js";
+import type { Triple } from "./schemas.js";
+export interface FactsResult {
+    facts: Triple[];
+}
+/**
+ * Extract instance-level facts from a text chunk against the CURRENT state
+ * of the ontology store, AND the current state of the facts store — the
+ * latter is what lets entity reuse across documents actually happen.
+ */
+export declare function extractFacts(ontologyStore: OntologyStore, factsStore: FactsStore, text: string, apiKey: string): Promise<FactsResult>;

package/dist/facts.js

@@ -0,0 +1,49 @@
+import { render } from "./render.js";
+const FACTS_INSTRUCTIONS = `You are extracting FACTS (instance data) from the text below, typed against
+the domain ontology shown to you.
+
+Rules:
+- Check the "Known entities" list below FIRST. If the text refers to an
+  entity already listed there (even under a different name, abbreviation,
+  or phrasing — e.g. "Acme" vs "Acme Robotics Inc."), reuse its EXACT
+  existing IRI. Do not mint a new IRI for something that already exists.
+- Only mint a new "cd:" IRI for entities that are genuinely not in the
+  known entities list.
+- Type each new entity using rdf:type against an EXISTING class from the
+  ontology shown to you. Do not invent new classes here.
+- Reuse ontology properties (ex:...) for relationships between cd: entities.
+- Use lowercase_snake_case or lowerCamelCase local names under cd:.
+- Emit insert operations only.`;
+/**
+ * Extract instance-level facts from a text chunk against the CURRENT state
+ * of the ontology store, AND the current state of the facts store — the
+ * latter is what lets entity reuse across documents actually happen.
+ */
+export async function extractFacts(ontologyStore, factsStore, text, apiKey) {
+    const ontologyTurtle = await ontologyStore.toTurtle();
+    const knownEntities = factsStore.getEntitySummary();
+    const combinedContext = [
+        ontologyTurtle,
+        "",
+        "# Known entities (reuse these IRIs if the text refers to them):",
+        knownEntities,
+    ].join("\n");
+    const update = await render({
+        apiKey,
+        instructions: FACTS_INSTRUCTIONS,
+        ontologySnapshotTurtle: combinedContext,
+        text,
+    });
+    const facts = update.triple_operations
+        .filter((op) => op.type === "insert")
+        .flatMap((op) => op.triples);
+    const safe = facts.filter((t) => {
+        const violatesNamespace = t.subject.startsWith("ex:");
+        if (violatesNamespace) {
+            console.warn(`Dropped fact minted directly under ontology namespace: ${JSON.stringify(t)}`);
+        }
+        return !violatesNamespace;
+    });
+    const added = factsStore.addNew(safe);
+    return { facts: added };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { OntologyStore, type OntologyVersion } from "./store.js";
+export { FactsStore } from "./factStore.js";
+export { complementInserts } from "./diff.js";
+export { evolveOntology, type OntologyUpdateResult } from "./ontology.js";
+export { extractFacts, type FactsResult } from "./facts.js";
+export { queryGraph } from "./query.js";
+export { searchEntities, type SearchResult } from "./search.js";
+export { TripleSchema, TripleOpSchema, GraphUpdateSchema, type Triple, type TripleOp, type GraphUpdate, } from "./schemas.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export { OntologyStore } from "./store.js";
+export { FactsStore } from "./factStore.js";
+export { complementInserts } from "./diff.js";
+export { evolveOntology } from "./ontology.js";
+export { extractFacts } from "./facts.js";
+export { queryGraph } from "./query.js";
+export { searchEntities } from "./search.js";
+export { TripleSchema, TripleOpSchema, GraphUpdateSchema, } from "./schemas.js";

package/dist/ontology.d.ts

@@ -0,0 +1,12 @@
+import { OntologyStore, type OntologyVersion } from "./store.js";
+import type { Triple } from "./schemas.js";
+export interface OntologyUpdateResult {
+    added: Triple[];
+    version: OntologyVersion;
+}
+/**
+ * Run one document chunk through the ontology-proposal loop against a
+ * live OntologyStore, mutating it in place with only the genuinely new
+ * triples.
+ */
+export declare function evolveOntology(store: OntologyStore, text: string, apiKey: string): Promise<OntologyUpdateResult>;

package/dist/ontology.js

@@ -0,0 +1,38 @@
+import { render } from "./render.js";
+import { complementInserts } from "./diff.js";
+const ONTOLOGY_INSTRUCTIONS = `You are proposing additions to a domain ontology (RDFS/OWL schema: classes and
+properties only — no instance data) so that it can represent the concepts in
+the text below. You will be shown the ontology as it currently exists.
+
+Rules:
+- Reuse any class or property already in the ontology if it fits. Do not
+  re-propose triples that already exist in the snapshot shown to you.
+- Only propose NEW classes/properties for concepts the current ontology
+  cannot represent.
+- Use rdfs:Class, rdf:Property, rdfs:subClassOf, rdfs:domain, rdfs:range,
+  rdfs:label, rdfs:comment as needed. Prefix new terms with "ex:".
+- Emit insert operations only — this pass never deletes.
+- If the ontology already fully covers this text, return an empty
+  triple_operations list.`;
+/**
+ * Run one document chunk through the ontology-proposal loop against a
+ * live OntologyStore, mutating it in place with only the genuinely new
+ * triples.
+ */
+export async function evolveOntology(store, text, apiKey) {
+    const snapshotTurtle = await store.toTurtle();
+    const snapshotKeys = store.snapshotKeys();
+    const update = await render({
+        apiKey,
+        instructions: ONTOLOGY_INSTRUCTIONS,
+        ontologySnapshotTurtle: snapshotTurtle,
+        text,
+    });
+    const proposedInserts = update.triple_operations
+        .filter((op) => op.type === "insert")
+        .flatMap((op) => op.triples);
+    const genuinelyNew = complementInserts(proposedInserts, snapshotKeys, store.prefixes);
+    const added = store.addNew(genuinelyNew);
+    const version = await store.commitVersion();
+    return { added, version };
+}

package/dist/query.d.ts

@@ -0,0 +1,9 @@
+import type * as RDF from "@rdfjs/types";
+/**
+ * Run a SPARQL SELECT query across one or more RDF sources (e.g. an
+ * OntologyStore's and a FactsStore's rdfSource) and return plain,
+ * JSON-friendly rows. This is the query_graph() half of the exposure
+ * layer — the agent writes the SPARQL, this just executes it locally,
+ * no LLM call involved.
+ */
+export declare function queryGraph(sparql: string, sources: RDF.Source[]): Promise<Record<string, string>[]>;

package/dist/query.js

@@ -0,0 +1,22 @@
+import { QueryEngine } from "@comunica/query-sparql-rdfjs";
+const engine = new QueryEngine();
+/**
+ * Run a SPARQL SELECT query across one or more RDF sources (e.g. an
+ * OntologyStore's and a FactsStore's rdfSource) and return plain,
+ * JSON-friendly rows. This is the query_graph() half of the exposure
+ * layer — the agent writes the SPARQL, this just executes it locally,
+ * no LLM call involved.
+ */
+export async function queryGraph(sparql, sources) {
+    const bindingsStream = await engine.queryBindings(sparql, {
+        sources: sources,
+    });
+    const bindings = await bindingsStream.toArray();
+    return bindings.map((binding) => {
+        const row = {};
+        for (const [variable, term] of binding) {
+            row[variable.value] = term.value;
+        }
+        return row;
+    });
+}

package/dist/render.d.ts

@@ -0,0 +1,16 @@
+import { type GraphUpdate } from "./schemas.js";
+export interface RenderOptions {
+    apiKey: string;
+    model?: string;
+    /** What this render call is trying to produce — ontology proposal vs. facts. */
+    instructions: string;
+    /** Current ontology, serialized as Turtle, given as context. */
+    ontologySnapshotTurtle: string;
+    /** The document chunk being processed. */
+    text: string;
+}
+/**
+ * One LLM call: given instructions, an ontology snapshot, and a text chunk,
+ * get back a validated GraphUpdate.
+ */
+export declare function render(opts: RenderOptions): Promise<GraphUpdate>;

package/dist/render.js

@@ -0,0 +1,52 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { GraphUpdateSchema } from "./schemas.js";
+const TOOL_NAME = "emit_graph_update";
+// Anthropic's tool input_schema wants a plain JSON Schema object, not a $ref
+// wrapper — zod-to-json-schema produces the latter by default, so unwrap it.
+function graphUpdateJsonSchema() {
+    const schema = zodToJsonSchema(GraphUpdateSchema, "GraphUpdate");
+    return schema.definitions?.GraphUpdate ?? schema;
+}
+/**
+ * One LLM call: given instructions, an ontology snapshot, and a text chunk,
+ * get back a validated GraphUpdate.
+ */
+export async function render(opts) {
+    const client = new Anthropic({ apiKey: opts.apiKey });
+    const response = await client.messages.create({
+        model: opts.model ?? "claude-sonnet-4-6",
+        max_tokens: 4096,
+        tools: [
+            {
+                name: TOOL_NAME,
+                description: "Emit RDF triple insert/delete operations representing your proposed change, as structured data.",
+                input_schema: graphUpdateJsonSchema(),
+            },
+        ],
+        tool_choice: { type: "tool", name: TOOL_NAME },
+        messages: [
+            {
+                role: "user",
+                content: [
+                    opts.instructions,
+                    "",
+                    "Current ontology (Turtle):",
+                    "```turtle",
+                    opts.ontologySnapshotTurtle || "# (empty — no ontology yet)",
+                    "```",
+                    "",
+                    "Text to process:",
+                    "```",
+                    opts.text,
+                    "```",
+                ].join("\n"),
+            },
+        ],
+    });
+    const toolUse = response.content.find((block) => block.type === "tool_use");
+    if (!toolUse) {
+        throw new Error("Model did not return a tool_use block — no structured output produced.");
+    }
+    return GraphUpdateSchema.parse(toolUse.input);
+}

package/dist/schemas.d.ts

@@ -0,0 +1,111 @@
+import { z } from "zod";
+/**
+ * A single triple, expressed as three IRIs/literals in string form.
+ * Kept flat (not N3 Quad objects) because this is the shape the LLM
+ * actually produces and validates against — conversion to N3 terms
+ * happens after parsing, in store.ts.
+ */
+export declare const TripleSchema: z.ZodObject<{
+    subject: z.ZodString;
+    predicate: z.ZodString;
+    object: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    object: string;
+    subject: string;
+    predicate: string;
+}, {
+    object: string;
+    subject: string;
+    predicate: string;
+}>;
+export type Triple = z.infer<typeof TripleSchema>;
+/**
+ * One insert or delete operation over a set of triples.
+ * An ordered list of these forms a GraphUpdate.
+ */
+export declare const TripleOpSchema: z.ZodObject<{
+    type: z.ZodEnum<["insert", "delete"]>;
+    triples: z.ZodArray<z.ZodObject<{
+        subject: z.ZodString;
+        predicate: z.ZodString;
+        object: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        object: string;
+        subject: string;
+        predicate: string;
+    }, {
+        object: string;
+        subject: string;
+        predicate: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "insert" | "delete";
+    triples: {
+        object: string;
+        subject: string;
+        predicate: string;
+    }[];
+}, {
+    type: "insert" | "delete";
+    triples: {
+        object: string;
+        subject: string;
+        predicate: string;
+    }[];
+}>;
+export type TripleOp = z.infer<typeof TripleOpSchema>;
+/**
+ * The full structured output the LLM must return for a render step —
+ * ontology proposal or facts extraction alike.
+ */
+export declare const GraphUpdateSchema: z.ZodObject<{
+    triple_operations: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<["insert", "delete"]>;
+        triples: z.ZodArray<z.ZodObject<{
+            subject: z.ZodString;
+            predicate: z.ZodString;
+            object: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            object: string;
+            subject: string;
+            predicate: string;
+        }, {
+            object: string;
+            subject: string;
+            predicate: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        type: "insert" | "delete";
+        triples: {
+            object: string;
+            subject: string;
+            predicate: string;
+        }[];
+    }, {
+        type: "insert" | "delete";
+        triples: {
+            object: string;
+            subject: string;
+            predicate: string;
+        }[];
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    triple_operations: {
+        type: "insert" | "delete";
+        triples: {
+            object: string;
+            subject: string;
+            predicate: string;
+        }[];
+    }[];
+}, {
+    triple_operations: {
+        type: "insert" | "delete";
+        triples: {
+            object: string;
+            subject: string;
+            predicate: string;
+        }[];
+    }[];
+}>;
+export type GraphUpdate = z.infer<typeof GraphUpdateSchema>;

package/dist/schemas.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+/**
+ * A single triple, expressed as three IRIs/literals in string form.
+ * Kept flat (not N3 Quad objects) because this is the shape the LLM
+ * actually produces and validates against — conversion to N3 terms
+ * happens after parsing, in store.ts.
+ */
+export const TripleSchema = z.object({
+    subject: z.string().describe("Subject IRI, e.g. 'ex:AcmeRobotics'"),
+    predicate: z.string().describe("Predicate IRI, e.g. 'rdf:type' or 'ex:hasIssuer'"),
+    object: z
+        .string()
+        .describe("Object IRI or literal. Literals should be quoted, e.g. '\"340000000\"^^xsd:decimal'. IRIs are unquoted, e.g. 'ex:Company'."),
+});
+/**
+ * One insert or delete operation over a set of triples.
+ * An ordered list of these forms a GraphUpdate.
+ */
+export const TripleOpSchema = z.object({
+    type: z.enum(["insert", "delete"]),
+    triples: z.array(TripleSchema),
+});
+/**
+ * The full structured output the LLM must return for a render step —
+ * ontology proposal or facts extraction alike.
+ */
+export const GraphUpdateSchema = z.object({
+    triple_operations: z.array(TripleOpSchema),
+});

package/dist/search.d.ts

@@ -0,0 +1,13 @@
+import type { FactsStore } from "./factStore.js";
+export interface SearchResult {
+    iri: string;
+    label: string;
+}
+/**
+ * Find entities in the facts store whose rdfs:label loosely matches the
+ * query text. Deliberately simple (case-insensitive substring match) for
+ * this first pass — an agent that knows roughly what it's looking for
+ * ("Acme") but not the exact IRI ("cd:acme_robotics_inc") uses this to
+ * resolve one before it, not both.
+ */
+export declare function searchEntities(query: string, factsStore: FactsStore): SearchResult[];

package/dist/search.js

@@ -0,0 +1,18 @@
+const RDFS_LABEL = "http://www.w3.org/2000/01/rdf-schema#label";
+/**
+ * Find entities in the facts store whose rdfs:label loosely matches the
+ * query text. Deliberately simple (case-insensitive substring match) for
+ * this first pass — an agent that knows roughly what it's looking for
+ * ("Acme") but not the exact IRI ("cd:acme_robotics_inc") uses this to
+ * resolve one before it, not both.
+ */
+export function searchEntities(query, factsStore) {
+    const needle = query.toLowerCase();
+    const results = [];
+    for (const quad of factsStore.rdfSource.getQuads(null, null, null, null)) {
+        if (quad.predicate.value === RDFS_LABEL && quad.object.value.toLowerCase().includes(needle)) {
+            results.push({ iri: quad.subject.value, label: quad.object.value });
+        }
+    }
+    return results;
+}

package/dist/store.d.ts

@@ -0,0 +1,40 @@
+import { Store, type Quad } from "n3";
+import type { Triple } from "./schemas.js";
+/**
+ * Convert one flat Triple (subject/predicate/object as strings, possibly
+ * using prefixed names or quoted literals) into an N3 Quad, by parsing it
+ * as a one-line Turtle snippet. Reuses N3's parser instead of hand-rolling
+ * IRI/literal handling.
+ */
+export declare function tripleToQuad(triple: Triple, prefixes: Record<string, string>): Quad;
+export interface OntologyVersion {
+    hash: string;
+    parentHash: string | null;
+    size: number;
+}
+/**
+ * Versioned in-memory ontology graph. One instance = one ontology's
+ * current state plus enough history to explain how it got there.
+ */
+export declare class OntologyStore {
+    readonly prefixes: Record<string, string>;
+    private store;
+    private hash;
+    private parentHash;
+    constructor(prefixes: Record<string, string>);
+    /** All quads currently in the store, as canonical keys — the "snapshot" for diffing. */
+    snapshotKeys(): Set<string>;
+    /** Serialize the current store to Turtle text — what gets shown to the LLM as context. */
+    toTurtle(): Promise<string>;
+    /**
+     * Add triples that are NOT already present (by exact subject/predicate/object
+     * match). Returns only the triples actually added — i.e. the genuine delta.
+     */
+    addNew(triples: Triple[]): Triple[];
+    get size(): number;
+    /** Raw RDF/JS-compatible store, for Comunica SPARQL queries. */
+    get rdfSource(): Store;
+    /** Recompute content hash and bump version lineage (parentHash = previous hash). */
+    commitVersion(): Promise<OntologyVersion>;
+    get currentVersion(): OntologyVersion;
+}

package/dist/store.js

@@ -0,0 +1,89 @@
+import { Parser, Store, Writer } from "n3";
+import { createHash } from "node:crypto";
+/** Build "@prefix x: <...> ." declaration lines for a prefix map. */
+function prefixDecls(prefixes) {
+    return Object.entries(prefixes)
+        .map(([p, ns]) => `@prefix ${p}: <${ns}> .`)
+        .join("\n");
+}
+/**
+ * Convert one flat Triple (subject/predicate/object as strings, possibly
+ * using prefixed names or quoted literals) into an N3 Quad, by parsing it
+ * as a one-line Turtle snippet. Reuses N3's parser instead of hand-rolling
+ * IRI/literal handling.
+ */
+export function tripleToQuad(triple, prefixes) {
+    const turtle = `${prefixDecls(prefixes)}\n${triple.subject} ${triple.predicate} ${triple.object} .`;
+    const quads = new Parser().parse(turtle);
+    if (quads.length !== 1) {
+        throw new Error(`Expected exactly one quad from triple ${JSON.stringify(triple)}, got ${quads.length}. Check IRI/literal syntax.`);
+    }
+    return quads[0];
+}
+/** Canonical string key for a quad, used for exact-match diffing. */
+function quadKey(q) {
+    return `${q.subject.value}\u0000${q.predicate.value}\u0000${q.object.value}\u0000${q.object.termType === "Literal" ? q.object.datatype?.value ?? "" : ""}`;
+}
+/**
+ * Versioned in-memory ontology graph. One instance = one ontology's
+ * current state plus enough history to explain how it got there.
+ */
+export class OntologyStore {
+    prefixes;
+    store = new Store();
+    hash = null;
+    parentHash = null;
+    constructor(prefixes) {
+        this.prefixes = prefixes;
+    }
+    /** All quads currently in the store, as canonical keys — the "snapshot" for diffing. */
+    snapshotKeys() {
+        return new Set(this.store.getQuads(null, null, null, null).map(quadKey));
+    }
+    /** Serialize the current store to Turtle text — what gets shown to the LLM as context. */
+    toTurtle() {
+        return new Promise((resolve, reject) => {
+            const writer = new Writer({ prefixes: this.prefixes });
+            for (const quad of this.store.getQuads(null, null, null, null)) {
+                writer.addQuad(quad);
+            }
+            writer.end((err, result) => (err ? reject(err) : resolve(result)));
+        });
+    }
+    /**
+     * Add triples that are NOT already present (by exact subject/predicate/object
+     * match). Returns only the triples actually added — i.e. the genuine delta.
+     */
+    addNew(triples) {
+        const existing = this.snapshotKeys();
+        const added = [];
+        for (const t of triples) {
+            const quad = tripleToQuad(t, this.prefixes);
+            if (!existing.has(quadKey(quad))) {
+                this.store.addQuad(quad);
+                existing.add(quadKey(quad));
+                added.push(t);
+            }
+        }
+        return added;
+    }
+    get size() {
+        return this.store.getQuads(null, null, null, null).length;
+    }
+    /** Raw RDF/JS-compatible store, for Comunica SPARQL queries. */
+    get rdfSource() {
+        return this.store;
+    }
+    /** Recompute content hash and bump version lineage (parentHash = previous hash). */
+    async commitVersion() {
+        const turtle = await this.toTurtle();
+        const canonical = turtle.split("\n").filter(Boolean).sort().join("\n");
+        const newHash = createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+        this.parentHash = this.hash;
+        this.hash = newHash;
+        return { hash: this.hash, parentHash: this.parentHash, size: this.size };
+    }
+    get currentVersion() {
+        return { hash: this.hash ?? "unversioned", parentHash: this.parentHash, size: this.size };
+    }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "hyphal",
+  "version": "0.1.0",
+  "main": "./dist/index.js",
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx --env-file=.env src/cli.ts",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "keywords": [
+    "rdf",
+    "ontology",
+    "knowledge-graph",
+    "llm",
+    "agent",
+    "sparql"
+  ],
+  "author": "Atharva Deshpande",
+  "license": "MIT",
+  "description": "Ontology-co-evolving RDF extraction and querying for agents",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.122.0",
+    "@comunica/query-sparql-rdfjs": "^5.3.0",
+    "n3": "^1.26.0",
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "devDependencies": {
+    "@types/n3": "^1.26.3",
+    "@types/node": "^26.4.0",
+    "tsx": "^4.23.12",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "hyphal": "./dist/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Atharva91/hyphal.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Atharva91/hyphal/issues"
+  },
+  "homepage": "https://github.com/Atharva91/hyphal#readme"
+}