mindgraph 0.10.0 → 0.11.0

package/dist/index.d.mts

@@ -23,12 +23,24 @@ interface GraphEdge {
     updated_at: number;
     tombstone_at: number | null;
 }
+/**
+ * A `/retrieve` (text/semantic/hybrid) result. BREAKING (D3): the wire shape is
+ * `{node, score, legs?}` — the previous flat `{uid, label, summary, node_type,
+ * score}` never matched the server. Read fields off `.node` (e.g. `.node.uid`).
+ * With `include_sources: true`, `.node.source_documents` carries provenance.
+ */
 interface SearchResult {
-    uid: string;
-    label: string;
-    summary: string;
-    node_type: string;
+    node: GraphNode & {
+        source_documents?: Array<{
+            uid: string;
+            title: string;
+            ingested_by_name?: string;
+            occurred_at?: string;
+        }>;
+    };
     score: number;
+    /** Present only when the hybrid search ran with `explain: true`. */
+    legs?: LegContribution[];
 }
 /**
  * One retrieval leg's contribution to a fused hybrid result — the
@@ -401,6 +413,12 @@ interface RetrieveRequest {
      * timestamp (seconds). Filters by INGESTION time, not event time.
      */
     created_before?: number;
+    /**
+     * When true (`text`/`semantic`/`hybrid`), annotate each result's `node` with
+     * `source_documents` (`[{uid, title, ingested_by_name?, occurred_at?}]`) —
+     * provenance for citing "which teammate's notes" (D3). Requires server ≥ 1.8.0.
+     */
+    include_sources?: boolean;
 }
 interface TraverseRequest {
     action: "chain" | "neighborhood" | "path" | "subgraph" | "top_k_paths";
@@ -443,6 +461,16 @@ interface PageOffset {
     page: number;
     char_start: number;
 }
+/**
+ * A named participant in a conversation/transcript. Supplied at ingest so
+ * extraction can map generic speaker labels ("Interviewer:") to real people
+ * and attribute claims/preferences/demands to the named person.
+ */
+interface Participant {
+    name: string;
+    organization?: string;
+    role?: string;
+}
 interface IngestChunkRequest {
     content: string;
     chunk_type?: string;
@@ -451,6 +479,12 @@ interface IngestChunkRequest {
     label?: string;
     layers?: string[];
     agent_id?: string;
+    /**
+     * Optional ontology schema id. When set, the per-chunk ontology extraction
+     * pass runs inline after cognitive extraction and submits proposed domain
+     * objects/relations. Presence alone triggers it.
+     */
+    ontology_schema_id?: string;
 }
 interface IngestChunkResponse {
     chunk_uid: string;
@@ -489,6 +523,18 @@ interface IngestDocumentRequest {
     mime_type?: string;
     /** Re-ingest even if a document with the same content was already ingested. */
     force_reingest?: boolean;
+    /**
+     * Optional ontology schema id. When set, the ontology extraction pass runs
+     * after cognitive passes. Presence alone triggers it (no `"ontology"` layer
+     * required), so auto-classified documents still get typed extraction.
+     */
+    ontology_schema_id?: string;
+    /** Named conversation participants — maps speaker labels to real people. */
+    participants?: Participant[];
+    /** When the document/conversation occurred (ISO-8601, imprecision ok). */
+    occurred_at?: string;
+    /** Free-text context grounding attribution during extraction. */
+    context?: string;
 }
 interface IngestDocumentResponse {
     job_id: string;
@@ -504,6 +550,14 @@ interface IngestSessionRequest {
     chunk_overlap?: number;
     layers?: string[];
     agent_id?: string;
+    /** Optional ontology schema id — triggers the ontology post-pass over the transcript's chunks. */
+    ontology_schema_id?: string;
+    /** Named conversation participants — maps speaker labels to real people. */
+    participants?: Participant[];
+    /** When the conversation occurred (ISO-8601, imprecision ok). */
+    occurred_at?: string;
+    /** Free-text context grounding attribution during extraction. */
+    context?: string;
 }
 interface RetrieveContextRequest {
     query: string;
@@ -593,6 +647,10 @@ interface RetrieveContextResponse {
             source_documents?: {
                 uid: string;
                 title: string;
+                /** User id of the teammate who ingested the source document (A4). */
+                ingested_by?: string;
+                /** Display name (else email) of the ingesting teammate. */
+                ingested_by_name?: string;
             }[];
             source_chunks?: SourceChunk[];
             believed_by?: BelievedBy[];
@@ -1046,6 +1104,17 @@ interface LinkDomainObjectsRequest {
     confidence?: number;
     agent_id?: string;
 }
+interface CreateDomainObjectRequest {
+    schema_id: string;
+    object_type: string;
+    canonical_name: string;
+    fields?: Record<string, unknown>;
+    aliases?: string[];
+    identity?: Record<string, unknown>;
+    confidence?: number;
+    /** Skip the same-type + same-name duplicate guard (default false). */
+    allow_duplicate?: boolean;
+}
 interface ExtractOntologyRequest {
     ontology_schema_id: string;
     source_uids: string[];
@@ -1558,6 +1627,37 @@ declare class MindGraph {
             score: number;
         }>;
     }>;
+    /**
+     * Per-object-type coverage stats for a schema (C2f): field fill rates
+     * (with a `near_empty` flag < 5%) and identity collisions, over a bounded
+     * per-type sample (default 500, max 2000).
+     */
+    ontologyStats(schemaId: string, sample?: number): Promise<{
+        schema_id: string;
+        object_types: Array<{
+            object_type: string;
+            count: number;
+            sampled: boolean;
+            fields: Array<{
+                name: string;
+                fill_rate: number;
+                near_empty: boolean;
+            }>;
+            collisions: Array<{
+                identity: string;
+                uids: string[];
+            }>;
+        }>;
+    }>;
+    /**
+     * Create a domain object by hand (auto-approved). Returns the created node
+     * uid + the audit proposal id. Throws 409 if an object of the same type +
+     * canonical_name already exists, unless `allow_duplicate` is set.
+     */
+    createDomainObject(req: CreateDomainObjectRequest): Promise<{
+        uid: string;
+        proposal_id: string;
+    }>;
     linkDomainObjects(req: LinkDomainObjectsRequest): Promise<{
         edge_uid: string;
     }>;
@@ -1566,4 +1666,4 @@ declare class MindGraph {
     }>;
 }
 
-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 };
+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 Participant, 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

@@ -23,12 +23,24 @@ interface GraphEdge {
     updated_at: number;
     tombstone_at: number | null;
 }
+/**
+ * A `/retrieve` (text/semantic/hybrid) result. BREAKING (D3): the wire shape is
+ * `{node, score, legs?}` — the previous flat `{uid, label, summary, node_type,
+ * score}` never matched the server. Read fields off `.node` (e.g. `.node.uid`).
+ * With `include_sources: true`, `.node.source_documents` carries provenance.
+ */
 interface SearchResult {
-    uid: string;
-    label: string;
-    summary: string;
-    node_type: string;
+    node: GraphNode & {
+        source_documents?: Array<{
+            uid: string;
+            title: string;
+            ingested_by_name?: string;
+            occurred_at?: string;
+        }>;
+    };
     score: number;
+    /** Present only when the hybrid search ran with `explain: true`. */
+    legs?: LegContribution[];
 }
 /**
  * One retrieval leg's contribution to a fused hybrid result — the
@@ -401,6 +413,12 @@ interface RetrieveRequest {
      * timestamp (seconds). Filters by INGESTION time, not event time.
      */
     created_before?: number;
+    /**
+     * When true (`text`/`semantic`/`hybrid`), annotate each result's `node` with
+     * `source_documents` (`[{uid, title, ingested_by_name?, occurred_at?}]`) —
+     * provenance for citing "which teammate's notes" (D3). Requires server ≥ 1.8.0.
+     */
+    include_sources?: boolean;
 }
 interface TraverseRequest {
     action: "chain" | "neighborhood" | "path" | "subgraph" | "top_k_paths";
@@ -443,6 +461,16 @@ interface PageOffset {
     page: number;
     char_start: number;
 }
+/**
+ * A named participant in a conversation/transcript. Supplied at ingest so
+ * extraction can map generic speaker labels ("Interviewer:") to real people
+ * and attribute claims/preferences/demands to the named person.
+ */
+interface Participant {
+    name: string;
+    organization?: string;
+    role?: string;
+}
 interface IngestChunkRequest {
     content: string;
     chunk_type?: string;
@@ -451,6 +479,12 @@ interface IngestChunkRequest {
     label?: string;
     layers?: string[];
     agent_id?: string;
+    /**
+     * Optional ontology schema id. When set, the per-chunk ontology extraction
+     * pass runs inline after cognitive extraction and submits proposed domain
+     * objects/relations. Presence alone triggers it.
+     */
+    ontology_schema_id?: string;
 }
 interface IngestChunkResponse {
     chunk_uid: string;
@@ -489,6 +523,18 @@ interface IngestDocumentRequest {
     mime_type?: string;
     /** Re-ingest even if a document with the same content was already ingested. */
     force_reingest?: boolean;
+    /**
+     * Optional ontology schema id. When set, the ontology extraction pass runs
+     * after cognitive passes. Presence alone triggers it (no `"ontology"` layer
+     * required), so auto-classified documents still get typed extraction.
+     */
+    ontology_schema_id?: string;
+    /** Named conversation participants — maps speaker labels to real people. */
+    participants?: Participant[];
+    /** When the document/conversation occurred (ISO-8601, imprecision ok). */
+    occurred_at?: string;
+    /** Free-text context grounding attribution during extraction. */
+    context?: string;
 }
 interface IngestDocumentResponse {
     job_id: string;
@@ -504,6 +550,14 @@ interface IngestSessionRequest {
     chunk_overlap?: number;
     layers?: string[];
     agent_id?: string;
+    /** Optional ontology schema id — triggers the ontology post-pass over the transcript's chunks. */
+    ontology_schema_id?: string;
+    /** Named conversation participants — maps speaker labels to real people. */
+    participants?: Participant[];
+    /** When the conversation occurred (ISO-8601, imprecision ok). */
+    occurred_at?: string;
+    /** Free-text context grounding attribution during extraction. */
+    context?: string;
 }
 interface RetrieveContextRequest {
     query: string;
@@ -593,6 +647,10 @@ interface RetrieveContextResponse {
             source_documents?: {
                 uid: string;
                 title: string;
+                /** User id of the teammate who ingested the source document (A4). */
+                ingested_by?: string;
+                /** Display name (else email) of the ingesting teammate. */
+                ingested_by_name?: string;
             }[];
             source_chunks?: SourceChunk[];
             believed_by?: BelievedBy[];
@@ -1046,6 +1104,17 @@ interface LinkDomainObjectsRequest {
     confidence?: number;
     agent_id?: string;
 }
+interface CreateDomainObjectRequest {
+    schema_id: string;
+    object_type: string;
+    canonical_name: string;
+    fields?: Record<string, unknown>;
+    aliases?: string[];
+    identity?: Record<string, unknown>;
+    confidence?: number;
+    /** Skip the same-type + same-name duplicate guard (default false). */
+    allow_duplicate?: boolean;
+}
 interface ExtractOntologyRequest {
     ontology_schema_id: string;
     source_uids: string[];
@@ -1558,6 +1627,37 @@ declare class MindGraph {
             score: number;
         }>;
     }>;
+    /**
+     * Per-object-type coverage stats for a schema (C2f): field fill rates
+     * (with a `near_empty` flag < 5%) and identity collisions, over a bounded
+     * per-type sample (default 500, max 2000).
+     */
+    ontologyStats(schemaId: string, sample?: number): Promise<{
+        schema_id: string;
+        object_types: Array<{
+            object_type: string;
+            count: number;
+            sampled: boolean;
+            fields: Array<{
+                name: string;
+                fill_rate: number;
+                near_empty: boolean;
+            }>;
+            collisions: Array<{
+                identity: string;
+                uids: string[];
+            }>;
+        }>;
+    }>;
+    /**
+     * Create a domain object by hand (auto-approved). Returns the created node
+     * uid + the audit proposal id. Throws 409 if an object of the same type +
+     * canonical_name already exists, unless `allow_duplicate` is set.
+     */
+    createDomainObject(req: CreateDomainObjectRequest): Promise<{
+        uid: string;
+        proposal_id: string;
+    }>;
     linkDomainObjects(req: LinkDomainObjectsRequest): Promise<{
         edge_uid: string;
     }>;
@@ -1566,4 +1666,4 @@ declare class MindGraph {
     }>;
 }
 
-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 };
+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 Participant, 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

@@ -812,6 +812,24 @@ var MindGraph = class {
   async searchDomainObjects(query, opts) {
     return this.post("/ontology/objects/search", { query, ...opts ?? {} });
   }
+  /**
+   * Per-object-type coverage stats for a schema (C2f): field fill rates
+   * (with a `near_empty` flag < 5%) and identity collisions, over a bounded
+   * per-type sample (default 500, max 2000).
+   */
+  async ontologyStats(schemaId, sample) {
+    const q = new URLSearchParams({ schema_id: schemaId });
+    if (sample != null) q.set("sample", String(sample));
+    return this.get(`/ontology/stats?${q.toString()}`);
+  }
+  /**
+   * Create a domain object by hand (auto-approved). Returns the created node
+   * uid + the audit proposal id. Throws 409 if an object of the same type +
+   * canonical_name already exists, unless `allow_duplicate` is set.
+   */
+  async createDomainObject(req) {
+    return this.post("/v1/ontology/objects", req);
+  }
   async linkDomainObjects(req) {
     return this.post("/ontology/relation", { action: "create", ...req });
   }

package/dist/index.mjs

@@ -785,6 +785,24 @@ var MindGraph = class {
   async searchDomainObjects(query, opts) {
     return this.post("/ontology/objects/search", { query, ...opts ?? {} });
   }
+  /**
+   * Per-object-type coverage stats for a schema (C2f): field fill rates
+   * (with a `near_empty` flag < 5%) and identity collisions, over a bounded
+   * per-type sample (default 500, max 2000).
+   */
+  async ontologyStats(schemaId, sample) {
+    const q = new URLSearchParams({ schema_id: schemaId });
+    if (sample != null) q.set("sample", String(sample));
+    return this.get(`/ontology/stats?${q.toString()}`);
+  }
+  /**
+   * Create a domain object by hand (auto-approved). Returns the created node
+   * uid + the audit proposal id. Throws 409 if an object of the same type +
+   * canonical_name already exists, unless `allow_duplicate` is set.
+   */
+  async createDomainObject(req) {
+    return this.post("/v1/ontology/objects", req);
+  }
   async linkDomainObjects(req) {
     return this.post("/ontology/relation", { action: "create", ...req });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindgraph",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "TypeScript client for the MindGraph Cloud API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",