mindgraph 0.4.1 → 0.6.0

package/dist/index.d.mts

@@ -30,6 +30,29 @@ interface SearchResult {
     node_type: string;
     score: number;
 }
+/**
+ * One retrieval leg's contribution to a fused hybrid result — the
+ * "why retrieved" detail. The fused score reconstructs exactly as
+ * `Σ 1/(60 + rank)` over a result's legs.
+ */
+interface LegContribution {
+    /** Which leg surfaced the result: `"fts"` (keyword/BM25) or `"vec"` (vector). */
+    leg: string;
+    /** 1-based within-leg rank the fusion used. */
+    rank: number;
+    /**
+     * The leg's raw score (BM25 relevance for `fts`, cosine similarity for
+     * `vec`). Not comparable across legs — RRF fuses by rank, not score.
+     */
+    score: number;
+}
+/** A `/retrieve` hybrid result: the full node plus the fused RRF score. */
+interface HybridSearchResult {
+    node: GraphNode;
+    score: number;
+    /** Per-leg contributions; present only when the request set `explain: true`. */
+    legs?: LegContribution[];
+}
 interface SearchChunk {
     chunk_uid: string;
     content: string;
@@ -329,6 +352,12 @@ interface RetrieveRequest {
     salience_min?: number;
     limit?: number;
     offset?: number;
+    /**
+     * Hybrid action only: attach per-leg contributions (`legs`) to each
+     * result — the "why retrieved" detail. Requires server ≥ 1.2.0; older
+     * servers ignore the field.
+     */
+    explain?: boolean;
 }
 interface TraverseRequest {
     action: "chain" | "neighborhood" | "path" | "subgraph";
@@ -617,6 +646,208 @@ interface MindGraphConfig {
     /** Initial backoff in ms before first retry. Doubles each attempt. Default: 1000. */
     retryBackoffMs?: number;
 }
+/** Field schema entry inside `OntologyObjectType.fields_json`. */
+interface FieldDefinition {
+    name: string;
+    /** One of: string|number|integer|boolean|date|datetime|enum|reference|array|object|json */
+    type: string;
+    required?: boolean;
+    description?: string;
+    default?: unknown;
+    enum?: string[];
+    reference_object_type?: string;
+    array_item_type?: string;
+    extraction_hint?: string;
+}
+interface OntologySchema {
+    id: string;
+    org_id: string;
+    name: string;
+    description?: string;
+    status: "draft" | "active" | "deprecated" | "archived";
+    version: number;
+    propose_status?: "pending" | "running" | "ready" | "failed" | null;
+    propose_job_id?: string | null;
+    propose_error?: string | null;
+    created_by?: string | null;
+    updated_by?: string | null;
+    created_at: string;
+    updated_at: string;
+    activated_at?: string | null;
+    archived_at?: string | null;
+}
+interface OntologyObjectType {
+    id: string;
+    schema_id: string;
+    org_id: string;
+    name: string;
+    display_name?: string | null;
+    description?: string | null;
+    fields_json: FieldDefinition[];
+    required_fields: string[];
+    identity_fields: string[];
+    aliases: string[];
+    examples_json: Record<string, unknown>[];
+    extraction_hints?: string | null;
+    default_confidence: number;
+    review_policy: "always" | "low_confidence" | "never";
+    status: "active" | "deprecated" | "archived";
+    version: number;
+    created_at: string;
+    updated_at: string;
+}
+interface OntologyRelationType {
+    id: string;
+    schema_id: string;
+    org_id: string;
+    name: string;
+    display_name?: string | null;
+    description?: string | null;
+    source_type: string;
+    target_type: string;
+    cardinality?: "one_to_one" | "one_to_many" | "many_to_many" | null;
+    symmetric: boolean;
+    transitive: boolean;
+    inverse_relation_type?: string | null;
+    fields_json: FieldDefinition[];
+    extraction_hints?: string | null;
+    review_policy: "always" | "low_confidence" | "never";
+    status: "active" | "deprecated" | "archived";
+    version: number;
+    created_at: string;
+    updated_at: string;
+}
+interface OntologySchemaDetail extends OntologySchema {
+    object_types: OntologyObjectType[];
+    relation_types: OntologyRelationType[];
+}
+interface CreateOntologySchemaRequest {
+    name: string;
+    description?: string;
+}
+interface UpdateOntologySchemaRequest {
+    name?: string;
+    description?: string;
+}
+interface OntologyObjectTypeInput {
+    name: string;
+    display_name?: string;
+    description?: string;
+    fields?: FieldDefinition[];
+    required_fields?: string[];
+    identity_fields?: string[];
+    aliases?: string[];
+    examples?: Record<string, unknown>[];
+    extraction_hints?: string;
+    default_confidence?: number;
+    review_policy?: "always" | "low_confidence" | "never";
+}
+interface OntologyRelationTypeInput {
+    name: string;
+    display_name?: string;
+    description?: string;
+    source_type: string;
+    target_type: string;
+    cardinality?: "one_to_one" | "one_to_many" | "many_to_many";
+    symmetric?: boolean;
+    transitive?: boolean;
+    inverse_relation_type?: string;
+    fields?: FieldDefinition[];
+    extraction_hints?: string;
+    review_policy?: "always" | "low_confidence" | "never";
+}
+/** Status: pending | approved | approval_required | rejected | applied | apply_failed. */
+interface OntologyProposal {
+    id: string;
+    org_id: string;
+    schema_id: string;
+    proposal_type: string;
+    proposed_by_agent_id?: string | null;
+    source_uids: string[];
+    source_scope_ids: string[];
+    changes_json: {
+        adds: Array<Record<string, unknown>>;
+        updates: Array<Record<string, unknown>>;
+        removes: Array<Record<string, unknown>>;
+    };
+    rationale?: string | null;
+    confidence?: number | null;
+    risk_level?: string | null;
+    review_status: string;
+    approval_uid?: string | null;
+    proposed_node_uid?: string | null;
+    applied_job_id?: string | null;
+    applied_error?: string | null;
+    apply_attempt_count: number;
+    edited_by?: string | null;
+    edited_at?: string | null;
+    original_snapshot?: Record<string, unknown> | null;
+    requires_manual_resolution: boolean;
+    created_at: string;
+    resolved_at?: string | null;
+    resolved_by?: string | null;
+}
+interface ProposalEdits {
+    canonical_name?: string;
+    fields?: Record<string, unknown>;
+    aliases?: string[];
+}
+interface ProposeOntologySchemaRequest {
+    description?: string;
+    template_hint?: "client_services" | "healthcare" | "supply_chain" | "research_intel" | "custom";
+    source_uids?: string[];
+    source_documents?: Array<{
+        content: string;
+        title?: string;
+    }>;
+    target_use_case?: string;
+    example_objects?: string[];
+    example_queries?: string[];
+    desired_workflows?: string[];
+    parent_schema_id?: string;
+}
+interface OntologyQueryRequest {
+    query: string;
+    schema_id: string;
+    object_types?: string[];
+    include_cognitive_context?: boolean;
+    include_sources?: boolean;
+    depth?: number;
+    limit?: number;
+}
+interface OntologyQueryResponse {
+    objects: GraphNode[];
+    relations: GraphEdge[];
+    cognitive_context: Record<string, GraphNode[]>;
+    external_refs: unknown[];
+    graph: {
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    };
+    provenance: Array<{
+        node_uid: string;
+        source_uid: string;
+        text_span: string;
+    }>;
+    confidence: {
+        overall: number;
+    };
+    truncated?: Record<string, boolean>;
+}
+interface LinkDomainObjectsRequest {
+    from_uid: string;
+    to_uid: string;
+    relation_type: string;
+    fields?: Record<string, unknown>;
+    confidence?: number;
+    agent_id?: string;
+}
+interface ExtractOntologyRequest {
+    ontology_schema_id: string;
+    source_uids: string[];
+    mode?: "propose_only" | "respect_policies" | "force_auto_apply";
+}
+type DomainObject = GraphNode;
 
 declare class MindGraphError extends Error {
     status: number;
@@ -836,12 +1067,17 @@ declare class MindGraph {
         include_edges?: boolean;
         include_chunks?: boolean;
     }): Promise<SearchResult[] | EnrichedSearchResponse>;
-    /** Hybrid BM25 + vector search with reciprocal rank fusion. */
+    /**
+     * Hybrid BM25 + vector search with reciprocal rank fusion. Pass
+     * `explain: true` to get per-leg contributions (`legs`) on each result —
+     * the "why retrieved" detail (server ≥ 1.2.0; older servers ignore it).
+     */
     hybridSearch(query: string, opts?: {
         k?: number;
         node_types?: string[];
         layer?: string;
-    }): Promise<SearchResult[]>;
+        explain?: boolean;
+    }): Promise<HybridSearchResult[]>;
     getNodes(params?: {
         node_type?: string;
         layer?: string;
@@ -980,6 +1216,113 @@ declare class MindGraph {
      * Returns a `job_id` immediately; poll `getJob(id)` for progress.
      */
     runSynthesis(projectUid: string): Promise<SynthesisJobResponse>;
+    listOntologySchemas(): Promise<{
+        items: OntologySchema[];
+    }>;
+    getOntologySchema(id: string): Promise<OntologySchemaDetail>;
+    createOntologySchema(req: CreateOntologySchemaRequest): Promise<OntologySchema>;
+    updateOntologySchema(id: string, req: UpdateOntologySchemaRequest): Promise<OntologySchema>;
+    activateOntologySchema(id: string): Promise<OntologySchema>;
+    deprecateOntologySchema(id: string): Promise<OntologySchema>;
+    archiveOntologySchema(id: string): Promise<OntologySchema>;
+    /**
+     * Kick off an LLM-driven schema proposal job.
+     * Returns immediately with `{ schema_id, job_id }`; poll
+     * `getOntologySchema(schema_id)` for streaming progress.
+     */
+    proposeOntologySchema(req: ProposeOntologySchemaRequest): Promise<{
+        schema_id: string;
+        job_id: string;
+    }>;
+    testOntologySchema(id: string, opts?: {
+        example_queries?: string[];
+    }): Promise<{
+        job_id: string;
+    }>;
+    addOntologyObjectType(schemaId: string, req: OntologyObjectTypeInput): Promise<OntologyObjectType>;
+    updateOntologyObjectType(schemaId: string, typeId: string, req: Partial<OntologyObjectTypeInput>): Promise<OntologyObjectType>;
+    deleteOntologyObjectType(schemaId: string, typeId: string): Promise<OntologyObjectType>;
+    addOntologyRelationType(schemaId: string, req: OntologyRelationTypeInput): Promise<OntologyRelationType>;
+    updateOntologyRelationType(schemaId: string, typeId: string, req: Partial<OntologyRelationTypeInput>): Promise<OntologyRelationType>;
+    deleteOntologyRelationType(schemaId: string, typeId: string): Promise<OntologyRelationType>;
+    listOntologyProposals(opts?: {
+        status?: string;
+        schema_id?: string;
+        object_type?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        items: OntologyProposal[];
+        limit: number;
+        offset: number;
+    }>;
+    getOntologyProposal(id: string): Promise<OntologyProposal>;
+    patchOntologyProposal(id: string, req: {
+        edits: ProposalEdits;
+    }): Promise<OntologyProposal>;
+    approveOntologyProposal(id: string, opts?: {
+        feedback?: string;
+        edits?: ProposalEdits;
+    }): Promise<OntologyProposal>;
+    rejectOntologyProposal(id: string, reason?: string): Promise<OntologyProposal>;
+    applyOntologyProposal(id: string): Promise<{
+        id: string;
+        queued: boolean;
+    }>;
+    batchApproveOntologyProposals(ids: string[], feedback?: string): Promise<{
+        processed: string[];
+        skipped: {
+            id: string;
+            reason: string;
+        }[];
+    }>;
+    batchRejectOntologyProposals(ids: string[], reason?: string): Promise<{
+        processed: string[];
+        skipped: {
+            id: string;
+            reason: string;
+        }[];
+    }>;
+    queryOntology(req: OntologyQueryRequest): Promise<OntologyQueryResponse>;
+    getDomainObject(uid: string): Promise<DomainObject>;
+    getDomainObjectContext(uid: string, depth?: number): Promise<OntologyQueryResponse>;
+    getDomainObjectHistory(uid: string): Promise<{
+        versions: Array<{
+            version: number;
+            changed_at: string;
+            changed_by: string;
+            change_reason?: string;
+            snapshot: unknown;
+        }>;
+    }>;
+    listDomainObjects(opts: {
+        schema_id: string;
+        object_type?: string;
+        limit?: number;
+        offset?: number;
+        sort?: string;
+    }): Promise<{
+        items: DomainObject[];
+        limit: number;
+        offset: number;
+        has_more: boolean;
+    }>;
+    searchDomainObjects(query: string, opts?: {
+        schema_id?: string;
+        object_types?: string[];
+        limit?: number;
+    }): Promise<{
+        items: Array<{
+            object: DomainObject;
+            score: number;
+        }>;
+    }>;
+    linkDomainObjects(req: LinkDomainObjectsRequest): Promise<{
+        edge_uid: string;
+    }>;
+    extractOntology(req: ExtractOntologyRequest): Promise<{
+        job_id: string;
+    }>;
 }
 
 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 };

package/dist/index.d.ts

@@ -30,6 +30,29 @@ interface SearchResult {
     node_type: string;
     score: number;
 }
+/**
+ * One retrieval leg's contribution to a fused hybrid result — the
+ * "why retrieved" detail. The fused score reconstructs exactly as
+ * `Σ 1/(60 + rank)` over a result's legs.
+ */
+interface LegContribution {
+    /** Which leg surfaced the result: `"fts"` (keyword/BM25) or `"vec"` (vector). */
+    leg: string;
+    /** 1-based within-leg rank the fusion used. */
+    rank: number;
+    /**
+     * The leg's raw score (BM25 relevance for `fts`, cosine similarity for
+     * `vec`). Not comparable across legs — RRF fuses by rank, not score.
+     */
+    score: number;
+}
+/** A `/retrieve` hybrid result: the full node plus the fused RRF score. */
+interface HybridSearchResult {
+    node: GraphNode;
+    score: number;
+    /** Per-leg contributions; present only when the request set `explain: true`. */
+    legs?: LegContribution[];
+}
 interface SearchChunk {
     chunk_uid: string;
     content: string;
@@ -329,6 +352,12 @@ interface RetrieveRequest {
     salience_min?: number;
     limit?: number;
     offset?: number;
+    /**
+     * Hybrid action only: attach per-leg contributions (`legs`) to each
+     * result — the "why retrieved" detail. Requires server ≥ 1.2.0; older
+     * servers ignore the field.
+     */
+    explain?: boolean;
 }
 interface TraverseRequest {
     action: "chain" | "neighborhood" | "path" | "subgraph";
@@ -617,6 +646,208 @@ interface MindGraphConfig {
     /** Initial backoff in ms before first retry. Doubles each attempt. Default: 1000. */
     retryBackoffMs?: number;
 }
+/** Field schema entry inside `OntologyObjectType.fields_json`. */
+interface FieldDefinition {
+    name: string;
+    /** One of: string|number|integer|boolean|date|datetime|enum|reference|array|object|json */
+    type: string;
+    required?: boolean;
+    description?: string;
+    default?: unknown;
+    enum?: string[];
+    reference_object_type?: string;
+    array_item_type?: string;
+    extraction_hint?: string;
+}
+interface OntologySchema {
+    id: string;
+    org_id: string;
+    name: string;
+    description?: string;
+    status: "draft" | "active" | "deprecated" | "archived";
+    version: number;
+    propose_status?: "pending" | "running" | "ready" | "failed" | null;
+    propose_job_id?: string | null;
+    propose_error?: string | null;
+    created_by?: string | null;
+    updated_by?: string | null;
+    created_at: string;
+    updated_at: string;
+    activated_at?: string | null;
+    archived_at?: string | null;
+}
+interface OntologyObjectType {
+    id: string;
+    schema_id: string;
+    org_id: string;
+    name: string;
+    display_name?: string | null;
+    description?: string | null;
+    fields_json: FieldDefinition[];
+    required_fields: string[];
+    identity_fields: string[];
+    aliases: string[];
+    examples_json: Record<string, unknown>[];
+    extraction_hints?: string | null;
+    default_confidence: number;
+    review_policy: "always" | "low_confidence" | "never";
+    status: "active" | "deprecated" | "archived";
+    version: number;
+    created_at: string;
+    updated_at: string;
+}
+interface OntologyRelationType {
+    id: string;
+    schema_id: string;
+    org_id: string;
+    name: string;
+    display_name?: string | null;
+    description?: string | null;
+    source_type: string;
+    target_type: string;
+    cardinality?: "one_to_one" | "one_to_many" | "many_to_many" | null;
+    symmetric: boolean;
+    transitive: boolean;
+    inverse_relation_type?: string | null;
+    fields_json: FieldDefinition[];
+    extraction_hints?: string | null;
+    review_policy: "always" | "low_confidence" | "never";
+    status: "active" | "deprecated" | "archived";
+    version: number;
+    created_at: string;
+    updated_at: string;
+}
+interface OntologySchemaDetail extends OntologySchema {
+    object_types: OntologyObjectType[];
+    relation_types: OntologyRelationType[];
+}
+interface CreateOntologySchemaRequest {
+    name: string;
+    description?: string;
+}
+interface UpdateOntologySchemaRequest {
+    name?: string;
+    description?: string;
+}
+interface OntologyObjectTypeInput {
+    name: string;
+    display_name?: string;
+    description?: string;
+    fields?: FieldDefinition[];
+    required_fields?: string[];
+    identity_fields?: string[];
+    aliases?: string[];
+    examples?: Record<string, unknown>[];
+    extraction_hints?: string;
+    default_confidence?: number;
+    review_policy?: "always" | "low_confidence" | "never";
+}
+interface OntologyRelationTypeInput {
+    name: string;
+    display_name?: string;
+    description?: string;
+    source_type: string;
+    target_type: string;
+    cardinality?: "one_to_one" | "one_to_many" | "many_to_many";
+    symmetric?: boolean;
+    transitive?: boolean;
+    inverse_relation_type?: string;
+    fields?: FieldDefinition[];
+    extraction_hints?: string;
+    review_policy?: "always" | "low_confidence" | "never";
+}
+/** Status: pending | approved | approval_required | rejected | applied | apply_failed. */
+interface OntologyProposal {
+    id: string;
+    org_id: string;
+    schema_id: string;
+    proposal_type: string;
+    proposed_by_agent_id?: string | null;
+    source_uids: string[];
+    source_scope_ids: string[];
+    changes_json: {
+        adds: Array<Record<string, unknown>>;
+        updates: Array<Record<string, unknown>>;
+        removes: Array<Record<string, unknown>>;
+    };
+    rationale?: string | null;
+    confidence?: number | null;
+    risk_level?: string | null;
+    review_status: string;
+    approval_uid?: string | null;
+    proposed_node_uid?: string | null;
+    applied_job_id?: string | null;
+    applied_error?: string | null;
+    apply_attempt_count: number;
+    edited_by?: string | null;
+    edited_at?: string | null;
+    original_snapshot?: Record<string, unknown> | null;
+    requires_manual_resolution: boolean;
+    created_at: string;
+    resolved_at?: string | null;
+    resolved_by?: string | null;
+}
+interface ProposalEdits {
+    canonical_name?: string;
+    fields?: Record<string, unknown>;
+    aliases?: string[];
+}
+interface ProposeOntologySchemaRequest {
+    description?: string;
+    template_hint?: "client_services" | "healthcare" | "supply_chain" | "research_intel" | "custom";
+    source_uids?: string[];
+    source_documents?: Array<{
+        content: string;
+        title?: string;
+    }>;
+    target_use_case?: string;
+    example_objects?: string[];
+    example_queries?: string[];
+    desired_workflows?: string[];
+    parent_schema_id?: string;
+}
+interface OntologyQueryRequest {
+    query: string;
+    schema_id: string;
+    object_types?: string[];
+    include_cognitive_context?: boolean;
+    include_sources?: boolean;
+    depth?: number;
+    limit?: number;
+}
+interface OntologyQueryResponse {
+    objects: GraphNode[];
+    relations: GraphEdge[];
+    cognitive_context: Record<string, GraphNode[]>;
+    external_refs: unknown[];
+    graph: {
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    };
+    provenance: Array<{
+        node_uid: string;
+        source_uid: string;
+        text_span: string;
+    }>;
+    confidence: {
+        overall: number;
+    };
+    truncated?: Record<string, boolean>;
+}
+interface LinkDomainObjectsRequest {
+    from_uid: string;
+    to_uid: string;
+    relation_type: string;
+    fields?: Record<string, unknown>;
+    confidence?: number;
+    agent_id?: string;
+}
+interface ExtractOntologyRequest {
+    ontology_schema_id: string;
+    source_uids: string[];
+    mode?: "propose_only" | "respect_policies" | "force_auto_apply";
+}
+type DomainObject = GraphNode;
 
 declare class MindGraphError extends Error {
     status: number;
@@ -836,12 +1067,17 @@ declare class MindGraph {
         include_edges?: boolean;
         include_chunks?: boolean;
     }): Promise<SearchResult[] | EnrichedSearchResponse>;
-    /** Hybrid BM25 + vector search with reciprocal rank fusion. */
+    /**
+     * Hybrid BM25 + vector search with reciprocal rank fusion. Pass
+     * `explain: true` to get per-leg contributions (`legs`) on each result —
+     * the "why retrieved" detail (server ≥ 1.2.0; older servers ignore it).
+     */
     hybridSearch(query: string, opts?: {
         k?: number;
         node_types?: string[];
         layer?: string;
-    }): Promise<SearchResult[]>;
+        explain?: boolean;
+    }): Promise<HybridSearchResult[]>;
     getNodes(params?: {
         node_type?: string;
         layer?: string;
@@ -980,6 +1216,113 @@ declare class MindGraph {
      * Returns a `job_id` immediately; poll `getJob(id)` for progress.
      */
     runSynthesis(projectUid: string): Promise<SynthesisJobResponse>;
+    listOntologySchemas(): Promise<{
+        items: OntologySchema[];
+    }>;
+    getOntologySchema(id: string): Promise<OntologySchemaDetail>;
+    createOntologySchema(req: CreateOntologySchemaRequest): Promise<OntologySchema>;
+    updateOntologySchema(id: string, req: UpdateOntologySchemaRequest): Promise<OntologySchema>;
+    activateOntologySchema(id: string): Promise<OntologySchema>;
+    deprecateOntologySchema(id: string): Promise<OntologySchema>;
+    archiveOntologySchema(id: string): Promise<OntologySchema>;
+    /**
+     * Kick off an LLM-driven schema proposal job.
+     * Returns immediately with `{ schema_id, job_id }`; poll
+     * `getOntologySchema(schema_id)` for streaming progress.
+     */
+    proposeOntologySchema(req: ProposeOntologySchemaRequest): Promise<{
+        schema_id: string;
+        job_id: string;
+    }>;
+    testOntologySchema(id: string, opts?: {
+        example_queries?: string[];
+    }): Promise<{
+        job_id: string;
+    }>;
+    addOntologyObjectType(schemaId: string, req: OntologyObjectTypeInput): Promise<OntologyObjectType>;
+    updateOntologyObjectType(schemaId: string, typeId: string, req: Partial<OntologyObjectTypeInput>): Promise<OntologyObjectType>;
+    deleteOntologyObjectType(schemaId: string, typeId: string): Promise<OntologyObjectType>;
+    addOntologyRelationType(schemaId: string, req: OntologyRelationTypeInput): Promise<OntologyRelationType>;
+    updateOntologyRelationType(schemaId: string, typeId: string, req: Partial<OntologyRelationTypeInput>): Promise<OntologyRelationType>;
+    deleteOntologyRelationType(schemaId: string, typeId: string): Promise<OntologyRelationType>;
+    listOntologyProposals(opts?: {
+        status?: string;
+        schema_id?: string;
+        object_type?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        items: OntologyProposal[];
+        limit: number;
+        offset: number;
+    }>;
+    getOntologyProposal(id: string): Promise<OntologyProposal>;
+    patchOntologyProposal(id: string, req: {
+        edits: ProposalEdits;
+    }): Promise<OntologyProposal>;
+    approveOntologyProposal(id: string, opts?: {
+        feedback?: string;
+        edits?: ProposalEdits;
+    }): Promise<OntologyProposal>;
+    rejectOntologyProposal(id: string, reason?: string): Promise<OntologyProposal>;
+    applyOntologyProposal(id: string): Promise<{
+        id: string;
+        queued: boolean;
+    }>;
+    batchApproveOntologyProposals(ids: string[], feedback?: string): Promise<{
+        processed: string[];
+        skipped: {
+            id: string;
+            reason: string;
+        }[];
+    }>;
+    batchRejectOntologyProposals(ids: string[], reason?: string): Promise<{
+        processed: string[];
+        skipped: {
+            id: string;
+            reason: string;
+        }[];
+    }>;
+    queryOntology(req: OntologyQueryRequest): Promise<OntologyQueryResponse>;
+    getDomainObject(uid: string): Promise<DomainObject>;
+    getDomainObjectContext(uid: string, depth?: number): Promise<OntologyQueryResponse>;
+    getDomainObjectHistory(uid: string): Promise<{
+        versions: Array<{
+            version: number;
+            changed_at: string;
+            changed_by: string;
+            change_reason?: string;
+            snapshot: unknown;
+        }>;
+    }>;
+    listDomainObjects(opts: {
+        schema_id: string;
+        object_type?: string;
+        limit?: number;
+        offset?: number;
+        sort?: string;
+    }): Promise<{
+        items: DomainObject[];
+        limit: number;
+        offset: number;
+        has_more: boolean;
+    }>;
+    searchDomainObjects(query: string, opts?: {
+        schema_id?: string;
+        object_types?: string[];
+        limit?: number;
+    }): Promise<{
+        items: Array<{
+            object: DomainObject;
+            score: number;
+        }>;
+    }>;
+    linkDomainObjects(req: LinkDomainObjectsRequest): Promise<{
+        edge_uid: string;
+    }>;
+    extractOntology(req: ExtractOntologyRequest): Promise<{
+        job_id: string;
+    }>;
 }
 
 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 };

package/dist/index.js

@@ -397,7 +397,11 @@ var MindGraph = class {
   async search(query, opts) {
     return this.post("/search", { query, ...opts });
   }
-  /** Hybrid BM25 + vector search with reciprocal rank fusion. */
+  /**
+   * Hybrid BM25 + vector search with reciprocal rank fusion. Pass
+   * `explain: true` to get per-leg contributions (`legs`) on each result —
+   * the "why retrieved" detail (server ≥ 1.2.0; older servers ignore it).
+   */
   async hybridSearch(query, opts) {
     return this.post("/retrieve", {
       action: "hybrid",
@@ -639,6 +643,136 @@ var MindGraph = class {
   async runSynthesis(projectUid) {
     return this.post(`/synthesis/run/${projectUid}`, {});
   }
+  // ============================================================================
+  // Operational Ontology Layer (Layer 7)
+  // ============================================================================
+  // ---- Schema management (cloud Postgres) ----
+  async listOntologySchemas() {
+    return this.get("/v1/ontology/schemas");
+  }
+  async getOntologySchema(id) {
+    return this.get(`/v1/ontology/schemas/${id}`);
+  }
+  async createOntologySchema(req) {
+    return this.post("/v1/ontology/schemas", req);
+  }
+  async updateOntologySchema(id, req) {
+    return this.patch(`/v1/ontology/schemas/${id}`, req);
+  }
+  async activateOntologySchema(id) {
+    return this.post(`/v1/ontology/schemas/${id}/activate`, {});
+  }
+  async deprecateOntologySchema(id) {
+    return this.post(`/v1/ontology/schemas/${id}/deprecate`, {});
+  }
+  async archiveOntologySchema(id) {
+    return this.del(`/v1/ontology/schemas/${id}`);
+  }
+  /**
+   * Kick off an LLM-driven schema proposal job.
+   * Returns immediately with `{ schema_id, job_id }`; poll
+   * `getOntologySchema(schema_id)` for streaming progress.
+   */
+  async proposeOntologySchema(req) {
+    return this.post("/v1/ontology/propose-schema", req);
+  }
+  async testOntologySchema(id, opts) {
+    return this.post(`/v1/ontology/schemas/${id}/test`, opts ?? {});
+  }
+  // ---- Schema sub-resources ----
+  async addOntologyObjectType(schemaId, req) {
+    return this.post(`/v1/ontology/schemas/${schemaId}/object-types`, req);
+  }
+  async updateOntologyObjectType(schemaId, typeId, req) {
+    return this.patch(
+      `/v1/ontology/schemas/${schemaId}/object-types/${typeId}`,
+      req
+    );
+  }
+  async deleteOntologyObjectType(schemaId, typeId) {
+    return this.del(
+      `/v1/ontology/schemas/${schemaId}/object-types/${typeId}`
+    );
+  }
+  async addOntologyRelationType(schemaId, req) {
+    return this.post(`/v1/ontology/schemas/${schemaId}/relation-types`, req);
+  }
+  async updateOntologyRelationType(schemaId, typeId, req) {
+    return this.patch(
+      `/v1/ontology/schemas/${schemaId}/relation-types/${typeId}`,
+      req
+    );
+  }
+  async deleteOntologyRelationType(schemaId, typeId) {
+    return this.del(
+      `/v1/ontology/schemas/${schemaId}/relation-types/${typeId}`
+    );
+  }
+  // ---- Proposals ----
+  async listOntologyProposals(opts) {
+    const q = new URLSearchParams();
+    if (opts?.status) q.set("status", opts.status);
+    if (opts?.schema_id) q.set("schema_id", opts.schema_id);
+    if (opts?.object_type) q.set("object_type", opts.object_type);
+    if (opts?.limit != null) q.set("limit", String(opts.limit));
+    if (opts?.offset != null) q.set("offset", String(opts.offset));
+    const qs = q.toString();
+    return this.get(`/v1/ontology/proposals${qs ? `?${qs}` : ""}`);
+  }
+  async getOntologyProposal(id) {
+    return this.get(`/v1/ontology/proposals/${id}`);
+  }
+  async patchOntologyProposal(id, req) {
+    return this.patch(`/v1/ontology/proposals/${id}`, req);
+  }
+  async approveOntologyProposal(id, opts) {
+    return this.post(`/v1/ontology/proposals/${id}/approve`, opts ?? {});
+  }
+  async rejectOntologyProposal(id, reason) {
+    return this.post(`/v1/ontology/proposals/${id}/reject`, { reason });
+  }
+  async applyOntologyProposal(id) {
+    return this.post(`/v1/ontology/proposals/${id}/apply`, {});
+  }
+  async batchApproveOntologyProposals(ids, feedback) {
+    return this.post("/v1/ontology/proposals/batch-approve", { ids, feedback });
+  }
+  async batchRejectOntologyProposals(ids, reason) {
+    return this.post("/v1/ontology/proposals/batch-reject", { ids, reason });
+  }
+  // ---- Retrieval (graph server) ----
+  async queryOntology(req) {
+    return this.post("/ontology/query", req);
+  }
+  async getDomainObject(uid) {
+    return this.get(`/ontology/object/${uid}`);
+  }
+  async getDomainObjectContext(uid, depth) {
+    const qs = depth != null ? `?depth=${depth}` : "";
+    return this.get(`/ontology/object/${uid}/context${qs}`);
+  }
+  async getDomainObjectHistory(uid) {
+    return this.get(`/ontology/object/${uid}/history`);
+  }
+  async listDomainObjects(opts) {
+    const q = new URLSearchParams();
+    q.set("schema_id", opts.schema_id);
+    if (opts.object_type) q.set("object_type", opts.object_type);
+    if (opts.limit != null) q.set("limit", String(opts.limit));
+    if (opts.offset != null) q.set("offset", String(opts.offset));
+    if (opts.sort) q.set("sort", opts.sort);
+    return this.get(`/ontology/objects?${q.toString()}`);
+  }
+  async searchDomainObjects(query, opts) {
+    return this.post("/ontology/objects/search", { query, ...opts ?? {} });
+  }
+  async linkDomainObjects(req) {
+    return this.post("/ontology/relation", { action: "create", ...req });
+  }
+  // ---- Extraction ----
+  async extractOntology(req) {
+    return this.post("/ontology/extract", req);
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -370,7 +370,11 @@ var MindGraph = class {
   async search(query, opts) {
     return this.post("/search", { query, ...opts });
   }
-  /** Hybrid BM25 + vector search with reciprocal rank fusion. */
+  /**
+   * Hybrid BM25 + vector search with reciprocal rank fusion. Pass
+   * `explain: true` to get per-leg contributions (`legs`) on each result —
+   * the "why retrieved" detail (server ≥ 1.2.0; older servers ignore it).
+   */
   async hybridSearch(query, opts) {
     return this.post("/retrieve", {
       action: "hybrid",
@@ -612,6 +616,136 @@ var MindGraph = class {
   async runSynthesis(projectUid) {
     return this.post(`/synthesis/run/${projectUid}`, {});
   }
+  // ============================================================================
+  // Operational Ontology Layer (Layer 7)
+  // ============================================================================
+  // ---- Schema management (cloud Postgres) ----
+  async listOntologySchemas() {
+    return this.get("/v1/ontology/schemas");
+  }
+  async getOntologySchema(id) {
+    return this.get(`/v1/ontology/schemas/${id}`);
+  }
+  async createOntologySchema(req) {
+    return this.post("/v1/ontology/schemas", req);
+  }
+  async updateOntologySchema(id, req) {
+    return this.patch(`/v1/ontology/schemas/${id}`, req);
+  }
+  async activateOntologySchema(id) {
+    return this.post(`/v1/ontology/schemas/${id}/activate`, {});
+  }
+  async deprecateOntologySchema(id) {
+    return this.post(`/v1/ontology/schemas/${id}/deprecate`, {});
+  }
+  async archiveOntologySchema(id) {
+    return this.del(`/v1/ontology/schemas/${id}`);
+  }
+  /**
+   * Kick off an LLM-driven schema proposal job.
+   * Returns immediately with `{ schema_id, job_id }`; poll
+   * `getOntologySchema(schema_id)` for streaming progress.
+   */
+  async proposeOntologySchema(req) {
+    return this.post("/v1/ontology/propose-schema", req);
+  }
+  async testOntologySchema(id, opts) {
+    return this.post(`/v1/ontology/schemas/${id}/test`, opts ?? {});
+  }
+  // ---- Schema sub-resources ----
+  async addOntologyObjectType(schemaId, req) {
+    return this.post(`/v1/ontology/schemas/${schemaId}/object-types`, req);
+  }
+  async updateOntologyObjectType(schemaId, typeId, req) {
+    return this.patch(
+      `/v1/ontology/schemas/${schemaId}/object-types/${typeId}`,
+      req
+    );
+  }
+  async deleteOntologyObjectType(schemaId, typeId) {
+    return this.del(
+      `/v1/ontology/schemas/${schemaId}/object-types/${typeId}`
+    );
+  }
+  async addOntologyRelationType(schemaId, req) {
+    return this.post(`/v1/ontology/schemas/${schemaId}/relation-types`, req);
+  }
+  async updateOntologyRelationType(schemaId, typeId, req) {
+    return this.patch(
+      `/v1/ontology/schemas/${schemaId}/relation-types/${typeId}`,
+      req
+    );
+  }
+  async deleteOntologyRelationType(schemaId, typeId) {
+    return this.del(
+      `/v1/ontology/schemas/${schemaId}/relation-types/${typeId}`
+    );
+  }
+  // ---- Proposals ----
+  async listOntologyProposals(opts) {
+    const q = new URLSearchParams();
+    if (opts?.status) q.set("status", opts.status);
+    if (opts?.schema_id) q.set("schema_id", opts.schema_id);
+    if (opts?.object_type) q.set("object_type", opts.object_type);
+    if (opts?.limit != null) q.set("limit", String(opts.limit));
+    if (opts?.offset != null) q.set("offset", String(opts.offset));
+    const qs = q.toString();
+    return this.get(`/v1/ontology/proposals${qs ? `?${qs}` : ""}`);
+  }
+  async getOntologyProposal(id) {
+    return this.get(`/v1/ontology/proposals/${id}`);
+  }
+  async patchOntologyProposal(id, req) {
+    return this.patch(`/v1/ontology/proposals/${id}`, req);
+  }
+  async approveOntologyProposal(id, opts) {
+    return this.post(`/v1/ontology/proposals/${id}/approve`, opts ?? {});
+  }
+  async rejectOntologyProposal(id, reason) {
+    return this.post(`/v1/ontology/proposals/${id}/reject`, { reason });
+  }
+  async applyOntologyProposal(id) {
+    return this.post(`/v1/ontology/proposals/${id}/apply`, {});
+  }
+  async batchApproveOntologyProposals(ids, feedback) {
+    return this.post("/v1/ontology/proposals/batch-approve", { ids, feedback });
+  }
+  async batchRejectOntologyProposals(ids, reason) {
+    return this.post("/v1/ontology/proposals/batch-reject", { ids, reason });
+  }
+  // ---- Retrieval (graph server) ----
+  async queryOntology(req) {
+    return this.post("/ontology/query", req);
+  }
+  async getDomainObject(uid) {
+    return this.get(`/ontology/object/${uid}`);
+  }
+  async getDomainObjectContext(uid, depth) {
+    const qs = depth != null ? `?depth=${depth}` : "";
+    return this.get(`/ontology/object/${uid}/context${qs}`);
+  }
+  async getDomainObjectHistory(uid) {
+    return this.get(`/ontology/object/${uid}/history`);
+  }
+  async listDomainObjects(opts) {
+    const q = new URLSearchParams();
+    q.set("schema_id", opts.schema_id);
+    if (opts.object_type) q.set("object_type", opts.object_type);
+    if (opts.limit != null) q.set("limit", String(opts.limit));
+    if (opts.offset != null) q.set("offset", String(opts.offset));
+    if (opts.sort) q.set("sort", opts.sort);
+    return this.get(`/ontology/objects?${q.toString()}`);
+  }
+  async searchDomainObjects(query, opts) {
+    return this.post("/ontology/objects/search", { query, ...opts ?? {} });
+  }
+  async linkDomainObjects(req) {
+    return this.post("/ontology/relation", { action: "create", ...req });
+  }
+  // ---- Extraction ----
+  async extractOntology(req) {
+    return this.post("/ontology/extract", req);
+  }
 };
 export {
   MindGraph,

package/package.json

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