mindgraph 0.7.0 → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Shuruheel Ahamed
+
+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

@@ -130,6 +130,27 @@ const { job_id } = await graph.runSynthesis(project.uid);
 const job = await graph.getJob(job_id);
 ```
 
+### Operational Ontology (Layer 7)
+
+Define typed domain objects (Customer, Order, Contract…) as a semantic contract and either **bind them to a SQL database** or extract them from documents — fused onto one object. Connecting a database (credentials/sync) is done in the dashboard; the SDK proposes/reviews schemas, queries, and lists the generated agent read tools.
+
+| Method | Description |
+|--------|-------------|
+| `proposeOntologySchema(req)` | Draft a schema from a description (+ optional sample docs); returns `{ schema_id, job_id }` |
+| `activateOntologySchema(id)` / `getOntologySchema(id)` / `listOntologySchemas()` | Schema lifecycle |
+| `listOntologyProposals(opts?)` / `approveOntologyProposal(id)` / `rejectOntologyProposal(id)` | Review extracted-object proposals |
+| `queryOntology({ query, include_cognitive_context })` | Typed retrieval with the cognitive overlay fused in |
+| `listOntologyTools()` | The generated read-tool manifest (`search_/get_/summarize_<obj>`) the MCP server renders |
+
+```typescript
+const { schema_id } = await graph.proposeOntologySchema({ description: "Clients, orders, contracts." });
+await graph.activateOntologySchema(schema_id);
+const { tools } = await graph.listOntologyTools();
+const ctx = await graph.queryOntology({ query: "Which customers are a churn risk?", include_cognitive_context: true });
+```
+
+See the [Operational Ontology](https://mindgraph.cloud/docs/ontology) and [Connect a database](https://mindgraph.cloud/docs/connect) docs.
+
 ### CRUD
 
 | Method | Description |

package/dist/index.d.mts

@@ -81,12 +81,20 @@ interface EnrichedSearchResponse {
     chunks: SearchChunk[];
 }
 interface PathStep {
-    uid: string;
+    node_uid: string;
     label: string;
     node_type: string;
     edge_type: string | null;
     depth: number;
     parent_uid: string | null;
+    /** Min-plus cost of the returned BFS path from the start node
+     * (sum of -ln(weight), weights clamped to (1e-9, 1]); cost of the path
+     * the traversal returned, not the cheapest path. 0 at the start node. */
+    path_cost?: number;
+    /** Product of edge confidences along the returned BFS path (clamped to
+     * (1e-9, 1]); a ranking signal, not a calibrated probability. 1 at the
+     * start node. */
+    path_confidence?: number;
 }
 interface PersonProps {
     canonical_name: string;
@@ -357,7 +365,17 @@ interface RetrieveRequest {
      * Retrieval action. Note: `"semantic"` requires a configured embedding
      * provider on the server; for semantic search use `retrieveContext()` instead.
      */
-    action: "text" | "semantic" | "hybrid" | "active_goals" | "open_questions" | "weak_claims" | "pending_approvals" | "unresolved_contradictions" | "layer" | "recent";
+    action: "text" | "semantic" | "hybrid" | "active_goals" | "open_questions" | "weak_claims" | "pending_approvals" | "unresolved_contradictions" | "preferences" | "layer" | "recent";
+    /**
+     * Required for `"text"`, `"semantic"`, `"hybrid"`. Optional for
+     * `"preferences"`: with a `query` you get topic-relevant preferences (the
+     * semantic leg bridges low lexical overlap — e.g. "suggest a hotel"
+     * surfaces a stored "loved the rooftop pool"); without one you get all
+     * preferences, most salient first. Either way the result is a
+     * `SearchResult[]` (score = relevance with a query, salience without).
+     * Use `"preferences"` for advice/recommendation requests so answers
+     * reflect what the user likes.
+     */
     query?: string;
     k?: number;
     threshold?: number;
@@ -373,6 +391,16 @@ interface RetrieveRequest {
      * servers ignore the field.
      */
     explain?: boolean;
+    /**
+     * `recent` action only: restrict to nodes created at/after this unix
+     * timestamp (seconds). Filters by INGESTION time, not event time.
+     */
+    created_after?: number;
+    /**
+     * `recent` action only: restrict to nodes created at/before this unix
+     * timestamp (seconds). Filters by INGESTION time, not event time.
+     */
+    created_before?: number;
 }
 interface TraverseRequest {
     action: "chain" | "neighborhood" | "path" | "subgraph";
@@ -399,6 +427,16 @@ interface EvolveRequest {
     version?: number;
     agent_id?: string;
 }
+/**
+ * Maps a 1-based page number to the **UTF-8 byte offset** where that page begins
+ * in `content`. `char_start` is a byte offset, NOT a codepoint count — count
+ * UTF-8 bytes (`new TextEncoder().encode(s).length`), not `s.length`, or pages
+ * will be wrong for any non-ASCII document.
+ */
+interface PageOffset {
+    page: number;
+    char_start: number;
+}
 interface IngestChunkRequest {
     content: string;
     chunk_type?: string;
@@ -437,10 +475,20 @@ interface IngestDocumentRequest {
     citation_count?: number;
     arxiv_id?: string;
     language?: string;
+    /** Per-page character offsets into `content`, used to map extractions back to source pages. */
+    page_offsets?: PageOffset[];
+    /** Total number of pages in the source document. */
+    page_count?: number;
+    /** MIME type of the original source (e.g. "application/pdf"). */
+    mime_type?: string;
+    /** Re-ingest even if a document with the same content was already ingested. */
+    force_reingest?: boolean;
 }
 interface IngestDocumentResponse {
     job_id: string;
     document_uid: string;
+    /** True when the document was recognized as a duplicate and ingestion was skipped. */
+    deduplicated?: boolean;
 }
 interface IngestSessionRequest {
     content: string;
@@ -478,6 +526,47 @@ interface ListArticlesResponse {
     total: number;
     has_more: boolean;
 }
+/**
+ * Citation provenance for a graph node: the source chunk span(s) the node was
+ * extracted from. Annotated onto retrieve-context graph nodes via `source_chunks`.
+ */
+interface SourceChunk {
+    chunk_uid: string;
+    /** UTF-8 byte offset into the chunk where the source span starts. */
+    char_start: number | null;
+    /** UTF-8 byte offset into the chunk where the source span ends. */
+    char_end: number | null;
+    /** 1-based page number where the span starts (null if no page map). */
+    page_start: number | null;
+    /** 1-based page number where the span ends (null if no page map). */
+    page_end: number | null;
+    /** The verbatim source span (when matched), else null. */
+    quote: string | null;
+    /**
+     * Web-Annotation-style selector object pinning the node to its source span,
+     * or null when no confident match. `start`/`end` are chunk-relative UTF-8 byte
+     * offsets; `exact` is the durable quote; `prefix`/`suffix` give re-anchoring context.
+     */
+    anchor: TextSelector | null;
+}
+/** A Web-Annotation quote+position selector (see `SourceChunk.anchor`). */
+interface TextSelector {
+    exact: string;
+    prefix: string;
+    suffix: string;
+    start: number;
+    end: number;
+}
+/**
+ * Per-agent stance on a Claim: which agent asserts it and with what certainty.
+ * Annotated onto retrieve-context graph nodes (Claim nodes) via `believed_by`.
+ */
+interface BelievedBy {
+    agent_uid: string;
+    agent_label: string;
+    /** The asserting agent's certainty in the claim, or null if unspecified. */
+    confidence: number | null;
+}
 interface RetrieveContextResponse {
     articles?: ArticleResult[];
     chunks?: {
@@ -494,6 +583,8 @@ interface RetrieveContextResponse {
                 uid: string;
                 title: string;
             }[];
+            source_chunks?: SourceChunk[];
+            believed_by?: BelievedBy[];
         })[];
         edges: Record<string, unknown>[];
     };
@@ -674,6 +765,63 @@ interface FieldDefinition {
     array_item_type?: string;
     extraction_hint?: string;
 }
+/**
+ * Datasource binding for an object type — the "semantic contract" mapping it to
+ * an external system (SQL today). Null/absent = extracted or authored.
+ * See docs/plans/layer7-semantic-contract.md §2.
+ */
+interface ObjectBacking {
+    kind: "sql";
+    /** MDO-ready list; exactly one source is supported today. */
+    sources: SqlBackingSource[];
+    /** Identity key, resolved via an indexed source_pk at sync time. */
+    primary_key: string;
+    title_field?: string;
+    sync?: BackingSync;
+}
+interface SqlBackingSource {
+    /** FK into external_connections — credentials live in secrets, never here. */
+    connection_ref: string;
+    table: string;
+    /** Join/identity key within this source. */
+    key: string;
+    filter?: BackingFilter;
+    /** object field name -> binding. Each field is owned by exactly one source. */
+    field_map: Record<string, FieldBinding>;
+}
+interface FieldBinding {
+    column: string;
+    /** indexed = projected/embedded/searchable; live = fetched on demand, never stored. */
+    mode?: "indexed" | "live";
+}
+/** Structured predicate (column op value) — never raw SQL. */
+interface BackingFilter {
+    column: string;
+    op: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "like" | "is_null" | "not_null";
+    value?: unknown;
+}
+interface BackingSync {
+    mode?: "incremental" | "full";
+    cursor_column?: string;
+    deleted_at_column?: string;
+    /** null = manual "Sync now"; cron later. */
+    schedule?: string | null;
+}
+/** Datasource binding for a relation type (FK column or M:M join table). */
+type RelationBacking = {
+    kind: "sql_fk";
+    connection_ref: string;
+    fk_table: string;
+    fk_column: string;
+    /** `table.column` the FK references (the other side's PK). */
+    references: string;
+} | {
+    kind: "sql_join_table";
+    connection_ref: string;
+    table: string;
+    from_column: string;
+    to_column: string;
+};
 interface OntologySchema {
     id: string;
     org_id: string;
@@ -706,6 +854,8 @@ interface OntologyObjectType {
     extraction_hints?: string | null;
     default_confidence: number;
     review_policy: "always" | "low_confidence" | "never";
+    /** Datasource binding (null = extracted/authored). */
+    backing?: ObjectBacking | null;
     status: "active" | "deprecated" | "archived";
     version: number;
     created_at: string;
@@ -727,6 +877,8 @@ interface OntologyRelationType {
     fields_json: FieldDefinition[];
     extraction_hints?: string | null;
     review_policy: "always" | "low_confidence" | "never";
+    /** Datasource binding (null = extracted/authored). */
+    backing?: RelationBacking | null;
     status: "active" | "deprecated" | "archived";
     version: number;
     created_at: string;
@@ -736,6 +888,16 @@ interface OntologySchemaDetail extends OntologySchema {
     object_types: OntologyObjectType[];
     relation_types: OntologyRelationType[];
 }
+/** A generated read-only tool descriptor (from `listOntologyTools`). */
+interface OntologyToolDescriptor {
+    name: string;
+    description: string;
+    schema_id: string;
+    object_type: string;
+    /** "search" | "object" | "object_context" */
+    maps_to: string;
+    input_schema: Record<string, unknown>;
+}
 interface CreateOntologySchemaRequest {
     name: string;
     description?: string;
@@ -756,6 +918,8 @@ interface OntologyObjectTypeInput {
     extraction_hints?: string;
     default_confidence?: number;
     review_policy?: "always" | "low_confidence" | "never";
+    /** Bind this object type to an external source (SQL). Omit for extracted/authored. */
+    backing?: ObjectBacking | null;
 }
 interface OntologyRelationTypeInput {
     name: string;
@@ -770,6 +934,8 @@ interface OntologyRelationTypeInput {
     fields?: FieldDefinition[];
     extraction_hints?: string;
     review_policy?: "always" | "low_confidence" | "never";
+    /** Bind this relation to an FK column or M:M join table. Both endpoints must be sql-mapped. */
+    backing?: RelationBacking | null;
 }
 /** Status: pending | approved | approval_required | rejected | applied | apply_failed. */
 interface OntologyProposal {
@@ -1175,6 +1341,10 @@ declare class MindGraph {
         documents_processed: number;
         node_source_pairs_added: number;
     }>;
+    /** Backfill citation anchors (source_chunks spans) for existing graphs. Returns a background job id. */
+    backfillAnchors(): Promise<{
+        job_id: string;
+    }>;
     listJobs(): Promise<Job[]>;
     getJob(id: string): Promise<Job>;
     cancelJob(id: string): Promise<unknown>;
@@ -1305,6 +1475,15 @@ declare class MindGraph {
         }[];
     }>;
     queryOntology(req: OntologyQueryRequest): Promise<OntologyQueryResponse>;
+    /**
+     * Read-only agent tool descriptors generated from the active ontology
+     * schema(s). Each maps to a generic `/ontology` read endpoint with
+     * `object_type` bound. Used by the MCP server to expose typed per-object
+     * tools (`search_customers`, `summarize_customer`, …).
+     */
+    listOntologyTools(): Promise<{
+        tools: OntologyToolDescriptor[];
+    }>;
     getDomainObject(uid: string): Promise<DomainObject>;
     getDomainObjectContext(uid: string, depth?: number): Promise<OntologyQueryResponse>;
     getDomainObjectHistory(uid: string): Promise<{
@@ -1346,4 +1525,4 @@ declare class MindGraph {
     }>;
 }
 
-export { type AnalogyCandidate, type ArgumentRequest, type ArticleResult, type BatchRequest, type CaptureRequest, type ClaimHub, type ClearResponse, type ClusterClaimSample, type ClusteredClaimHub, type CommitmentRequest, type ConceptCluster, type DecayRequest, type DeliberationRequest, type DialecticalPair, type DistillRequest, type DocumentRef, type EnrichedSearchResponse, type EntityBridge, type EntityRequest, type EpistemicCounts, type EventProps, type EvolveRequest, type ExecutionRequest, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type ListArticlesResponse, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type NationProps, type OrganizationProps, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type PurgeRequest, type RankedClaimHub, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SessionRequest, type SignalsQuery, type SignalsResponse, type StructureRequest, type SynthesisJobResponse, type TheorySupportGap, type TraverseRequest };
+export { type AnalogyCandidate, type ArgumentRequest, type ArticleResult, type BatchRequest, type BelievedBy, type CaptureRequest, type ClaimHub, type ClearResponse, type ClusterClaimSample, type ClusteredClaimHub, type CommitmentRequest, type ConceptCluster, type DecayRequest, type DeliberationRequest, type DialecticalPair, type DistillRequest, type DocumentRef, type EnrichedSearchResponse, type EntityBridge, type EntityRequest, type EpistemicCounts, type EventProps, type EvolveRequest, type ExecutionRequest, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type ListArticlesResponse, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type NationProps, type OrganizationProps, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type PurgeRequest, type RankedClaimHub, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SessionRequest, type SignalsQuery, type SignalsResponse, type SourceChunk, type StructureRequest, type SynthesisJobResponse, type TextSelector, type TheorySupportGap, type TraverseRequest };

package/dist/index.d.ts

@@ -81,12 +81,20 @@ interface EnrichedSearchResponse {
     chunks: SearchChunk[];
 }
 interface PathStep {
-    uid: string;
+    node_uid: string;
     label: string;
     node_type: string;
     edge_type: string | null;
     depth: number;
     parent_uid: string | null;
+    /** Min-plus cost of the returned BFS path from the start node
+     * (sum of -ln(weight), weights clamped to (1e-9, 1]); cost of the path
+     * the traversal returned, not the cheapest path. 0 at the start node. */
+    path_cost?: number;
+    /** Product of edge confidences along the returned BFS path (clamped to
+     * (1e-9, 1]); a ranking signal, not a calibrated probability. 1 at the
+     * start node. */
+    path_confidence?: number;
 }
 interface PersonProps {
     canonical_name: string;
@@ -357,7 +365,17 @@ interface RetrieveRequest {
      * Retrieval action. Note: `"semantic"` requires a configured embedding
      * provider on the server; for semantic search use `retrieveContext()` instead.
      */
-    action: "text" | "semantic" | "hybrid" | "active_goals" | "open_questions" | "weak_claims" | "pending_approvals" | "unresolved_contradictions" | "layer" | "recent";
+    action: "text" | "semantic" | "hybrid" | "active_goals" | "open_questions" | "weak_claims" | "pending_approvals" | "unresolved_contradictions" | "preferences" | "layer" | "recent";
+    /**
+     * Required for `"text"`, `"semantic"`, `"hybrid"`. Optional for
+     * `"preferences"`: with a `query` you get topic-relevant preferences (the
+     * semantic leg bridges low lexical overlap — e.g. "suggest a hotel"
+     * surfaces a stored "loved the rooftop pool"); without one you get all
+     * preferences, most salient first. Either way the result is a
+     * `SearchResult[]` (score = relevance with a query, salience without).
+     * Use `"preferences"` for advice/recommendation requests so answers
+     * reflect what the user likes.
+     */
     query?: string;
     k?: number;
     threshold?: number;
@@ -373,6 +391,16 @@ interface RetrieveRequest {
      * servers ignore the field.
      */
     explain?: boolean;
+    /**
+     * `recent` action only: restrict to nodes created at/after this unix
+     * timestamp (seconds). Filters by INGESTION time, not event time.
+     */
+    created_after?: number;
+    /**
+     * `recent` action only: restrict to nodes created at/before this unix
+     * timestamp (seconds). Filters by INGESTION time, not event time.
+     */
+    created_before?: number;
 }
 interface TraverseRequest {
     action: "chain" | "neighborhood" | "path" | "subgraph";
@@ -399,6 +427,16 @@ interface EvolveRequest {
     version?: number;
     agent_id?: string;
 }
+/**
+ * Maps a 1-based page number to the **UTF-8 byte offset** where that page begins
+ * in `content`. `char_start` is a byte offset, NOT a codepoint count — count
+ * UTF-8 bytes (`new TextEncoder().encode(s).length`), not `s.length`, or pages
+ * will be wrong for any non-ASCII document.
+ */
+interface PageOffset {
+    page: number;
+    char_start: number;
+}
 interface IngestChunkRequest {
     content: string;
     chunk_type?: string;
@@ -437,10 +475,20 @@ interface IngestDocumentRequest {
     citation_count?: number;
     arxiv_id?: string;
     language?: string;
+    /** Per-page character offsets into `content`, used to map extractions back to source pages. */
+    page_offsets?: PageOffset[];
+    /** Total number of pages in the source document. */
+    page_count?: number;
+    /** MIME type of the original source (e.g. "application/pdf"). */
+    mime_type?: string;
+    /** Re-ingest even if a document with the same content was already ingested. */
+    force_reingest?: boolean;
 }
 interface IngestDocumentResponse {
     job_id: string;
     document_uid: string;
+    /** True when the document was recognized as a duplicate and ingestion was skipped. */
+    deduplicated?: boolean;
 }
 interface IngestSessionRequest {
     content: string;
@@ -478,6 +526,47 @@ interface ListArticlesResponse {
     total: number;
     has_more: boolean;
 }
+/**
+ * Citation provenance for a graph node: the source chunk span(s) the node was
+ * extracted from. Annotated onto retrieve-context graph nodes via `source_chunks`.
+ */
+interface SourceChunk {
+    chunk_uid: string;
+    /** UTF-8 byte offset into the chunk where the source span starts. */
+    char_start: number | null;
+    /** UTF-8 byte offset into the chunk where the source span ends. */
+    char_end: number | null;
+    /** 1-based page number where the span starts (null if no page map). */
+    page_start: number | null;
+    /** 1-based page number where the span ends (null if no page map). */
+    page_end: number | null;
+    /** The verbatim source span (when matched), else null. */
+    quote: string | null;
+    /**
+     * Web-Annotation-style selector object pinning the node to its source span,
+     * or null when no confident match. `start`/`end` are chunk-relative UTF-8 byte
+     * offsets; `exact` is the durable quote; `prefix`/`suffix` give re-anchoring context.
+     */
+    anchor: TextSelector | null;
+}
+/** A Web-Annotation quote+position selector (see `SourceChunk.anchor`). */
+interface TextSelector {
+    exact: string;
+    prefix: string;
+    suffix: string;
+    start: number;
+    end: number;
+}
+/**
+ * Per-agent stance on a Claim: which agent asserts it and with what certainty.
+ * Annotated onto retrieve-context graph nodes (Claim nodes) via `believed_by`.
+ */
+interface BelievedBy {
+    agent_uid: string;
+    agent_label: string;
+    /** The asserting agent's certainty in the claim, or null if unspecified. */
+    confidence: number | null;
+}
 interface RetrieveContextResponse {
     articles?: ArticleResult[];
     chunks?: {
@@ -494,6 +583,8 @@ interface RetrieveContextResponse {
                 uid: string;
                 title: string;
             }[];
+            source_chunks?: SourceChunk[];
+            believed_by?: BelievedBy[];
         })[];
         edges: Record<string, unknown>[];
     };
@@ -674,6 +765,63 @@ interface FieldDefinition {
     array_item_type?: string;
     extraction_hint?: string;
 }
+/**
+ * Datasource binding for an object type — the "semantic contract" mapping it to
+ * an external system (SQL today). Null/absent = extracted or authored.
+ * See docs/plans/layer7-semantic-contract.md §2.
+ */
+interface ObjectBacking {
+    kind: "sql";
+    /** MDO-ready list; exactly one source is supported today. */
+    sources: SqlBackingSource[];
+    /** Identity key, resolved via an indexed source_pk at sync time. */
+    primary_key: string;
+    title_field?: string;
+    sync?: BackingSync;
+}
+interface SqlBackingSource {
+    /** FK into external_connections — credentials live in secrets, never here. */
+    connection_ref: string;
+    table: string;
+    /** Join/identity key within this source. */
+    key: string;
+    filter?: BackingFilter;
+    /** object field name -> binding. Each field is owned by exactly one source. */
+    field_map: Record<string, FieldBinding>;
+}
+interface FieldBinding {
+    column: string;
+    /** indexed = projected/embedded/searchable; live = fetched on demand, never stored. */
+    mode?: "indexed" | "live";
+}
+/** Structured predicate (column op value) — never raw SQL. */
+interface BackingFilter {
+    column: string;
+    op: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "like" | "is_null" | "not_null";
+    value?: unknown;
+}
+interface BackingSync {
+    mode?: "incremental" | "full";
+    cursor_column?: string;
+    deleted_at_column?: string;
+    /** null = manual "Sync now"; cron later. */
+    schedule?: string | null;
+}
+/** Datasource binding for a relation type (FK column or M:M join table). */
+type RelationBacking = {
+    kind: "sql_fk";
+    connection_ref: string;
+    fk_table: string;
+    fk_column: string;
+    /** `table.column` the FK references (the other side's PK). */
+    references: string;
+} | {
+    kind: "sql_join_table";
+    connection_ref: string;
+    table: string;
+    from_column: string;
+    to_column: string;
+};
 interface OntologySchema {
     id: string;
     org_id: string;
@@ -706,6 +854,8 @@ interface OntologyObjectType {
     extraction_hints?: string | null;
     default_confidence: number;
     review_policy: "always" | "low_confidence" | "never";
+    /** Datasource binding (null = extracted/authored). */
+    backing?: ObjectBacking | null;
     status: "active" | "deprecated" | "archived";
     version: number;
     created_at: string;
@@ -727,6 +877,8 @@ interface OntologyRelationType {
     fields_json: FieldDefinition[];
     extraction_hints?: string | null;
     review_policy: "always" | "low_confidence" | "never";
+    /** Datasource binding (null = extracted/authored). */
+    backing?: RelationBacking | null;
     status: "active" | "deprecated" | "archived";
     version: number;
     created_at: string;
@@ -736,6 +888,16 @@ interface OntologySchemaDetail extends OntologySchema {
     object_types: OntologyObjectType[];
     relation_types: OntologyRelationType[];
 }
+/** A generated read-only tool descriptor (from `listOntologyTools`). */
+interface OntologyToolDescriptor {
+    name: string;
+    description: string;
+    schema_id: string;
+    object_type: string;
+    /** "search" | "object" | "object_context" */
+    maps_to: string;
+    input_schema: Record<string, unknown>;
+}
 interface CreateOntologySchemaRequest {
     name: string;
     description?: string;
@@ -756,6 +918,8 @@ interface OntologyObjectTypeInput {
     extraction_hints?: string;
     default_confidence?: number;
     review_policy?: "always" | "low_confidence" | "never";
+    /** Bind this object type to an external source (SQL). Omit for extracted/authored. */
+    backing?: ObjectBacking | null;
 }
 interface OntologyRelationTypeInput {
     name: string;
@@ -770,6 +934,8 @@ interface OntologyRelationTypeInput {
     fields?: FieldDefinition[];
     extraction_hints?: string;
     review_policy?: "always" | "low_confidence" | "never";
+    /** Bind this relation to an FK column or M:M join table. Both endpoints must be sql-mapped. */
+    backing?: RelationBacking | null;
 }
 /** Status: pending | approved | approval_required | rejected | applied | apply_failed. */
 interface OntologyProposal {
@@ -1175,6 +1341,10 @@ declare class MindGraph {
         documents_processed: number;
         node_source_pairs_added: number;
     }>;
+    /** Backfill citation anchors (source_chunks spans) for existing graphs. Returns a background job id. */
+    backfillAnchors(): Promise<{
+        job_id: string;
+    }>;
     listJobs(): Promise<Job[]>;
     getJob(id: string): Promise<Job>;
     cancelJob(id: string): Promise<unknown>;
@@ -1305,6 +1475,15 @@ declare class MindGraph {
         }[];
     }>;
     queryOntology(req: OntologyQueryRequest): Promise<OntologyQueryResponse>;
+    /**
+     * Read-only agent tool descriptors generated from the active ontology
+     * schema(s). Each maps to a generic `/ontology` read endpoint with
+     * `object_type` bound. Used by the MCP server to expose typed per-object
+     * tools (`search_customers`, `summarize_customer`, …).
+     */
+    listOntologyTools(): Promise<{
+        tools: OntologyToolDescriptor[];
+    }>;
     getDomainObject(uid: string): Promise<DomainObject>;
     getDomainObjectContext(uid: string, depth?: number): Promise<OntologyQueryResponse>;
     getDomainObjectHistory(uid: string): Promise<{
@@ -1346,4 +1525,4 @@ declare class MindGraph {
     }>;
 }
 
-export { type AnalogyCandidate, type ArgumentRequest, type ArticleResult, type BatchRequest, type CaptureRequest, type ClaimHub, type ClearResponse, type ClusterClaimSample, type ClusteredClaimHub, type CommitmentRequest, type ConceptCluster, type DecayRequest, type DeliberationRequest, type DialecticalPair, type DistillRequest, type DocumentRef, type EnrichedSearchResponse, type EntityBridge, type EntityRequest, type EpistemicCounts, type EventProps, type EvolveRequest, type ExecutionRequest, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type ListArticlesResponse, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type NationProps, type OrganizationProps, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type PurgeRequest, type RankedClaimHub, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SessionRequest, type SignalsQuery, type SignalsResponse, type StructureRequest, type SynthesisJobResponse, type TheorySupportGap, type TraverseRequest };
+export { type AnalogyCandidate, type ArgumentRequest, type ArticleResult, type BatchRequest, type BelievedBy, type CaptureRequest, type ClaimHub, type ClearResponse, type ClusterClaimSample, type ClusteredClaimHub, type CommitmentRequest, type ConceptCluster, type DecayRequest, type DeliberationRequest, type DialecticalPair, type DistillRequest, type DocumentRef, type EnrichedSearchResponse, type EntityBridge, type EntityRequest, type EpistemicCounts, type EventProps, type EvolveRequest, type ExecutionRequest, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type ListArticlesResponse, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type NationProps, type OrganizationProps, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type PurgeRequest, type RankedClaimHub, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SessionRequest, type SignalsQuery, type SignalsResponse, type SourceChunk, type StructureRequest, type SynthesisJobResponse, type TextSelector, type TheorySupportGap, type TraverseRequest };

package/dist/index.js

@@ -559,6 +559,10 @@ var MindGraph = class {
   async backfillNodeSources() {
     return this.post("/backfill/node-sources", {});
   }
+  /** Backfill citation anchors (source_chunks spans) for existing graphs. Returns a background job id. */
+  async backfillAnchors() {
+    return this.post("/backfill/anchors", {});
+  }
   async listJobs() {
     return this.get("/jobs");
   }
@@ -752,6 +756,15 @@ var MindGraph = class {
   async queryOntology(req) {
     return this.post("/ontology/query", req);
   }
+  /**
+   * Read-only agent tool descriptors generated from the active ontology
+   * schema(s). Each maps to a generic `/ontology` read endpoint with
+   * `object_type` bound. Used by the MCP server to expose typed per-object
+   * tools (`search_customers`, `summarize_customer`, …).
+   */
+  async listOntologyTools() {
+    return this.get("/v1/ontology/tools");
+  }
   async getDomainObject(uid) {
     return this.get(`/ontology/object/${uid}`);
   }

package/dist/index.mjs

@@ -532,6 +532,10 @@ var MindGraph = class {
   async backfillNodeSources() {
     return this.post("/backfill/node-sources", {});
   }
+  /** Backfill citation anchors (source_chunks spans) for existing graphs. Returns a background job id. */
+  async backfillAnchors() {
+    return this.post("/backfill/anchors", {});
+  }
   async listJobs() {
     return this.get("/jobs");
   }
@@ -725,6 +729,15 @@ var MindGraph = class {
   async queryOntology(req) {
     return this.post("/ontology/query", req);
   }
+  /**
+   * Read-only agent tool descriptors generated from the active ontology
+   * schema(s). Each maps to a generic `/ontology` read endpoint with
+   * `object_type` bound. Used by the MCP server to expose typed per-object
+   * tools (`search_customers`, `summarize_customer`, …).
+   */
+  async listOntologyTools() {
+    return this.get("/v1/ontology/tools");
+  }
   async getDomainObject(uid) {
     return this.get(`/ontology/object/${uid}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindgraph",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "TypeScript client for the MindGraph Cloud API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -9,7 +9,9 @@
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "lint": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:offline": "vitest run src/offline.test.ts",
+    "test:e2e": "vitest run src/integration.test.ts"
   },
   "keywords": ["mindgraph", "knowledge-graph", "cognitive", "ai", "agent"],
   "license": "MIT",