mindgraph 0.3.0 → 0.4.1

package/README.md

@@ -52,16 +52,16 @@ new MindGraph({ baseUrl: string, apiKey?: string, jwt?: string })
 |--------|-------------|
 | `capture(req)` | Capture a source, snippet, or observation |
 | `entity(req)` | Create, alias, resolve, or merge entities |
-| `findOrCreateEntity(label, entityType?, agentId?)` | Convenience: create or find an entity by label (generic fallback) |
+| `findOrCreateEntity(label, props?, agentId?)` | Convenience: create or find an entity by label (generic fallback) |
 | `findOrCreatePerson(label, props?, agentId?)` | Find or create a Person entity |
 | `findOrCreateOrganization(label, props?, agentId?)` | Find or create an Organization entity |
 | `findOrCreateNation(label, props?, agentId?)` | Find or create a Nation entity |
 | `findOrCreateEvent(label, props?, agentId?)` | Find or create an Event entity |
 | `findOrCreatePlace(label, props?, agentId?)` | Find or create a Place entity |
 | `findOrCreateConcept(label, props?, agentId?)` | Find or create a Concept entity |
-| `addClaim(label, props?, agentId?)` | Add a Claim node |
-| `addEvidence(label, props?, agentId?)` | Add an Evidence node |
-| `addObservation(label, props?, agentId?)` | Add an Observation node |
+| `addClaim(label, content, confidence?, agentId?)` | Add a Claim node via the argument endpoint |
+| `addEvidence(label, description, agentId?)` | Add an Evidence node attached to a claim |
+| `addObservation(label, description, agentId?)` | Add an Observation node |
 
 **Typed entity example:**
 
@@ -113,6 +113,23 @@ const entity = await graph.findOrCreateEntity("Some Entity");
 | `governance(req)` | Create policies, set safety budgets, request/resolve approvals |
 | `execution(req)` | Track execution lifecycle and register agents |
 
+### Synthesis (Projects)
+
+Scope a corpus to a `Project` (via `commit({ action: "project", ... })` then link documents with `PartOfProject`), then mine cross-document signals and generate synthesis articles.
+
+| Method | Description |
+|--------|-------------|
+| `signals(projectUid, opts?)` | Mine cross-document structural signals for a project (entity bridges, claim hubs, theory gaps, concept clusters, analogies, dialectical pairs) |
+| `runSynthesis(projectUid)` | Spawn an async synthesis job that turns top clusters into Article nodes; returns a `job_id` to poll via `getJob()` |
+
+```typescript
+const project = await graph.commit({ action: "project", label: "Q2 China strategy" });
+// ...link documents to the project via PartOfProject edges...
+const signals = await graph.signals(project.uid, { signals: "clustered_claim_hubs,dialectical_pairs" });
+const { job_id } = await graph.runSynthesis(project.uid);
+const job = await graph.getJob(job_id);
+```
+
 ### CRUD
 
 | Method | Description |
@@ -171,16 +188,7 @@ const entity = await graph.findOrCreateEntity("Some Entity");
 | `health()` | Health check |
 | `stats()` | Graph-wide statistics |
 
-### Management (Cloud only)
-
-| Method | Description |
-|--------|-------------|
-| `signup(email, password)` | Create a new account |
-| `login(email, password)` | Login and receive JWT |
-| `createApiKey(name?)` | Create an API key |
-| `listApiKeys()` | List all API keys |
-| `revokeApiKey(id)` | Revoke an API key |
-| `getUsage()` | Get usage statistics |
+> Account sign-up, login, and API key management live in the [MindGraph dashboard](https://mindgraph.cloud/dashboard) — not the SDK. Get your API key there, then pass it to the `MindGraph` constructor.
 
 ## Examples
 

package/dist/index.d.mts

@@ -498,10 +498,120 @@ interface DecayRequest {
 interface PurgeRequest {
     before?: number;
 }
+interface SignalsQuery {
+    /**
+     * Comma-separated subset of signal names to compute, e.g.
+     * `"documents,entity_bridges,claim_hubs"`. If omitted, all signals run.
+     */
+    signals?: string;
+    /**
+     * Comma-separated node types used as filters for `entity_bridges` and
+     * `claim_hubs`. Defaults to the server's built-in target set
+     * (Person, Organization, Nation, Event, Place, Theory, Hypothesis,
+     * Pattern, Mechanism, Model, Analogy).
+     */
+    target_types?: string;
+}
+interface DocumentRef {
+    uid: string;
+    label: string;
+}
+interface EntityBridge {
+    uid: string;
+    label: string;
+    node_type: string;
+    doc_count: number;
+}
+interface ClaimHub {
+    target_uid: string;
+    target_label: string;
+    target_type: string;
+    claim_count: number;
+}
+interface RankedClaimHub {
+    target_uid: string;
+    target_label: string;
+    target_type: string;
+    claim_count: number;
+    distinct_doc_count: number;
+    project_doc_count: number;
+    dialectical_count: number;
+    score: number;
+    breadth_score: number;
+    tension_score: number;
+    density_score: number;
+}
+interface ClusterClaimSample {
+    uid: string;
+    label: string;
+    source_doc_label: string;
+}
+interface EpistemicCounts {
+    evidence: number;
+    arguments: number;
+    warrants: number;
+    theories_hypotheses: number;
+    contradicts_edges: number;
+}
+interface ClusteredClaimHub {
+    cluster_id: number;
+    size: number;
+    distinct_doc_count: number;
+    project_doc_count: number;
+    cohesion_score: number;
+    epistemic_density: number;
+    score: number;
+    breadth_score: number;
+    size_score: number;
+    dominant_entity_uid: string | null;
+    dominant_entity_label: string | null;
+    dominant_entity_type: string | null;
+    sample_claims: ClusterClaimSample[];
+    epistemic_counts: EpistemicCounts;
+}
+interface TheorySupportGap {
+    uid: string;
+    label: string;
+    node_type: string;
+    support_count: number;
+}
+interface ConceptCluster {
+    uid: string;
+    label: string;
+    doc_count: number;
+}
+interface AnalogyCandidate {
+    uid: string;
+    label: string;
+    summary: string;
+}
+interface DialecticalPair {
+    edge_type: string;
+    from_uid: string;
+    from_label: string;
+    to_uid: string;
+    to_label: string;
+}
+interface SignalsResponse {
+    project_uid: string;
+    documents: DocumentRef[];
+    entity_bridges: EntityBridge[];
+    claim_hubs: ClaimHub[];
+    ranked_claim_hubs: RankedClaimHub[];
+    clustered_claim_hubs: ClusteredClaimHub[];
+    theory_support_gaps: TheorySupportGap[];
+    concept_clusters: ConceptCluster[];
+    analogy_candidates: AnalogyCandidate[];
+    dialectical_pairs: DialecticalPair[];
+}
+interface SynthesisJobResponse {
+    job_id: string;
+}
 interface MindGraphConfig {
     baseUrl: string;
     apiKey?: string;
     jwt?: string;
+    orgId?: string;
     /** Max retries for 503 (server warming up) responses. Default: 3. Set to 0 to disable. */
     maxRetries?: number;
     /** Initial backoff in ms before first retry. Doubles each attempt. Default: 1000. */
@@ -852,6 +962,24 @@ declare class MindGraph {
     compileAll(): Promise<{
         job_id: string;
     }>;
+    /**
+     * Mine structural synthesis signals for a project's document corpus.
+     *
+     * Returns candidate surface for downstream synthesis — entity bridges
+     * across documents, claim hubs, clustered claim hubs, theory support
+     * gaps, concept clusters, analogy candidates, and dialectical pairs.
+     *
+     * Blocking operation. No LLM calls; Datalog + embedding clustering only.
+     */
+    signals(projectUid: string, opts?: SignalsQuery): Promise<SignalsResponse>;
+    /**
+     * Spawn a background synthesis job for a project: mines signals,
+     * selects top idea clusters, runs LLM synthesis, and persists
+     * candidate Article nodes linked via `Covers` edges.
+     *
+     * Returns a `job_id` immediately; poll `getJob(id)` for progress.
+     */
+    runSynthesis(projectUid: string): Promise<SynthesisJobResponse>;
 }
 
-export { type ArgumentRequest, type ArticleResult, type BatchRequest, type CaptureRequest, type ClearResponse, type CommitmentRequest, type DecayRequest, type DeliberationRequest, type DistillRequest, type EnrichedSearchResponse, type EntityRequest, 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 RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SessionRequest, type StructureRequest, type TraverseRequest };
+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

@@ -498,10 +498,120 @@ interface DecayRequest {
 interface PurgeRequest {
     before?: number;
 }
+interface SignalsQuery {
+    /**
+     * Comma-separated subset of signal names to compute, e.g.
+     * `"documents,entity_bridges,claim_hubs"`. If omitted, all signals run.
+     */
+    signals?: string;
+    /**
+     * Comma-separated node types used as filters for `entity_bridges` and
+     * `claim_hubs`. Defaults to the server's built-in target set
+     * (Person, Organization, Nation, Event, Place, Theory, Hypothesis,
+     * Pattern, Mechanism, Model, Analogy).
+     */
+    target_types?: string;
+}
+interface DocumentRef {
+    uid: string;
+    label: string;
+}
+interface EntityBridge {
+    uid: string;
+    label: string;
+    node_type: string;
+    doc_count: number;
+}
+interface ClaimHub {
+    target_uid: string;
+    target_label: string;
+    target_type: string;
+    claim_count: number;
+}
+interface RankedClaimHub {
+    target_uid: string;
+    target_label: string;
+    target_type: string;
+    claim_count: number;
+    distinct_doc_count: number;
+    project_doc_count: number;
+    dialectical_count: number;
+    score: number;
+    breadth_score: number;
+    tension_score: number;
+    density_score: number;
+}
+interface ClusterClaimSample {
+    uid: string;
+    label: string;
+    source_doc_label: string;
+}
+interface EpistemicCounts {
+    evidence: number;
+    arguments: number;
+    warrants: number;
+    theories_hypotheses: number;
+    contradicts_edges: number;
+}
+interface ClusteredClaimHub {
+    cluster_id: number;
+    size: number;
+    distinct_doc_count: number;
+    project_doc_count: number;
+    cohesion_score: number;
+    epistemic_density: number;
+    score: number;
+    breadth_score: number;
+    size_score: number;
+    dominant_entity_uid: string | null;
+    dominant_entity_label: string | null;
+    dominant_entity_type: string | null;
+    sample_claims: ClusterClaimSample[];
+    epistemic_counts: EpistemicCounts;
+}
+interface TheorySupportGap {
+    uid: string;
+    label: string;
+    node_type: string;
+    support_count: number;
+}
+interface ConceptCluster {
+    uid: string;
+    label: string;
+    doc_count: number;
+}
+interface AnalogyCandidate {
+    uid: string;
+    label: string;
+    summary: string;
+}
+interface DialecticalPair {
+    edge_type: string;
+    from_uid: string;
+    from_label: string;
+    to_uid: string;
+    to_label: string;
+}
+interface SignalsResponse {
+    project_uid: string;
+    documents: DocumentRef[];
+    entity_bridges: EntityBridge[];
+    claim_hubs: ClaimHub[];
+    ranked_claim_hubs: RankedClaimHub[];
+    clustered_claim_hubs: ClusteredClaimHub[];
+    theory_support_gaps: TheorySupportGap[];
+    concept_clusters: ConceptCluster[];
+    analogy_candidates: AnalogyCandidate[];
+    dialectical_pairs: DialecticalPair[];
+}
+interface SynthesisJobResponse {
+    job_id: string;
+}
 interface MindGraphConfig {
     baseUrl: string;
     apiKey?: string;
     jwt?: string;
+    orgId?: string;
     /** Max retries for 503 (server warming up) responses. Default: 3. Set to 0 to disable. */
     maxRetries?: number;
     /** Initial backoff in ms before first retry. Doubles each attempt. Default: 1000. */
@@ -852,6 +962,24 @@ declare class MindGraph {
     compileAll(): Promise<{
         job_id: string;
     }>;
+    /**
+     * Mine structural synthesis signals for a project's document corpus.
+     *
+     * Returns candidate surface for downstream synthesis — entity bridges
+     * across documents, claim hubs, clustered claim hubs, theory support
+     * gaps, concept clusters, analogy candidates, and dialectical pairs.
+     *
+     * Blocking operation. No LLM calls; Datalog + embedding clustering only.
+     */
+    signals(projectUid: string, opts?: SignalsQuery): Promise<SignalsResponse>;
+    /**
+     * Spawn a background synthesis job for a project: mines signals,
+     * selects top idea clusters, runs LLM synthesis, and persists
+     * candidate Article nodes linked via `Covers` edges.
+     *
+     * Returns a `job_id` immediately; poll `getJob(id)` for progress.
+     */
+    runSynthesis(projectUid: string): Promise<SynthesisJobResponse>;
 }
 
-export { type ArgumentRequest, type ArticleResult, type BatchRequest, type CaptureRequest, type ClearResponse, type CommitmentRequest, type DecayRequest, type DeliberationRequest, type DistillRequest, type EnrichedSearchResponse, type EntityRequest, 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 RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SessionRequest, type StructureRequest, type TraverseRequest };
+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

@@ -43,6 +43,9 @@ var MindGraph = class {
     } else if (config.jwt) {
       this.headers["Authorization"] = `Bearer ${config.jwt}`;
     }
+    if (config.orgId) {
+      this.headers["X-MindGraph-Org"] = config.orgId;
+    }
     this.maxRetries = config.maxRetries ?? 3;
     this.retryBackoffMs = config.retryBackoffMs ?? 1e3;
   }
@@ -609,6 +612,33 @@ var MindGraph = class {
   async compileAll() {
     return this.post("/wiki/compile/all", {});
   }
+  // ── Synthesis (Projects) ──────────────────────────────────────────────
+  /**
+   * Mine structural synthesis signals for a project's document corpus.
+   *
+   * Returns candidate surface for downstream synthesis — entity bridges
+   * across documents, claim hubs, clustered claim hubs, theory support
+   * gaps, concept clusters, analogy candidates, and dialectical pairs.
+   *
+   * Blocking operation. No LLM calls; Datalog + embedding clustering only.
+   */
+  async signals(projectUid, opts) {
+    const q = new URLSearchParams();
+    if (opts?.signals) q.set("signals", opts.signals);
+    if (opts?.target_types) q.set("target_types", opts.target_types);
+    const qs = q.toString();
+    return this.get(`/synthesis/signals/${projectUid}${qs ? `?${qs}` : ""}`);
+  }
+  /**
+   * Spawn a background synthesis job for a project: mines signals,
+   * selects top idea clusters, runs LLM synthesis, and persists
+   * candidate Article nodes linked via `Covers` edges.
+   *
+   * Returns a `job_id` immediately; poll `getJob(id)` for progress.
+   */
+  async runSynthesis(projectUid) {
+    return this.post(`/synthesis/run/${projectUid}`, {});
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -16,6 +16,9 @@ var MindGraph = class {
     } else if (config.jwt) {
       this.headers["Authorization"] = `Bearer ${config.jwt}`;
     }
+    if (config.orgId) {
+      this.headers["X-MindGraph-Org"] = config.orgId;
+    }
     this.maxRetries = config.maxRetries ?? 3;
     this.retryBackoffMs = config.retryBackoffMs ?? 1e3;
   }
@@ -582,6 +585,33 @@ var MindGraph = class {
   async compileAll() {
     return this.post("/wiki/compile/all", {});
   }
+  // ── Synthesis (Projects) ──────────────────────────────────────────────
+  /**
+   * Mine structural synthesis signals for a project's document corpus.
+   *
+   * Returns candidate surface for downstream synthesis — entity bridges
+   * across documents, claim hubs, clustered claim hubs, theory support
+   * gaps, concept clusters, analogy candidates, and dialectical pairs.
+   *
+   * Blocking operation. No LLM calls; Datalog + embedding clustering only.
+   */
+  async signals(projectUid, opts) {
+    const q = new URLSearchParams();
+    if (opts?.signals) q.set("signals", opts.signals);
+    if (opts?.target_types) q.set("target_types", opts.target_types);
+    const qs = q.toString();
+    return this.get(`/synthesis/signals/${projectUid}${qs ? `?${qs}` : ""}`);
+  }
+  /**
+   * Spawn a background synthesis job for a project: mines signals,
+   * selects top idea clusters, runs LLM synthesis, and persists
+   * candidate Article nodes linked via `Covers` edges.
+   *
+   * Returns a `job_id` immediately; poll `getJob(id)` for progress.
+   */
+  async runSynthesis(projectUid) {
+    return this.post(`/synthesis/run/${projectUid}`, {});
+  }
 };
 export {
   MindGraph,

package/package.json

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