mindgraph 0.1.0

package/README.md

@@ -0,0 +1,153 @@
+# mindgraph
+
+[![npm](https://img.shields.io/npm/v/mindgraph)](https://www.npmjs.com/package/mindgraph)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+TypeScript client for the [MindGraph Cloud](https://mindgraph.cloud) API — a structured semantic memory graph for AI agents.
+
+## Install
+
+```bash
+npm install mindgraph
+```
+
+## Quick Start
+
+```typescript
+import { MindGraph } from "mindgraph";
+
+const graph = new MindGraph({
+  baseUrl: "https://api.mindgraph.cloud",
+  apiKey: "mg_...",
+});
+
+// Add a node
+const node = await graph.addNode({
+  label: "User prefers dark mode",
+  node_type: "Preference",
+});
+
+// Search
+const results = await graph.search("what does the user prefer?");
+
+// Connect knowledge
+await graph.addLink({
+  from_uid: node.uid,
+  to_uid: "user_abc",
+  edge_type: "BelongsTo",
+});
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new MindGraph({ baseUrl: string, apiKey?: string, jwt?: string })
+```
+
+### Reality Layer
+
+| Method | Description |
+|--------|-------------|
+| `ingest(req)` | Ingest 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 |
+
+### Epistemic Layer
+
+| Method | Description |
+|--------|-------------|
+| `argue(req)` | Construct a full argument: claim + evidence + warrant + edges |
+| `inquire(req)` | Add hypothesis, theory, paradigm, anomaly, assumption, or question |
+| `structure(req)` | Add concept, pattern, mechanism, model, analogy, theorem, etc. |
+
+### Intent Layer
+
+| Method | Description |
+|--------|-------------|
+| `commit(req)` | Create a goal, project, or milestone |
+| `deliberate(req)` | Open decisions, add options/constraints, resolve decisions |
+
+### Action Layer
+
+| Method | Description |
+|--------|-------------|
+| `procedure(req)` | Build flows, add steps, affordances, and controls |
+| `risk(req)` | Assess risk or retrieve existing assessments |
+
+### Memory Layer
+
+| Method | Description |
+|--------|-------------|
+| `session(req)` | Open a session, record traces, or close a session |
+| `distill(req)` | Create a summary that distills multiple source nodes |
+| `memoryConfig(req)` | Set/get preferences and memory policies |
+
+### Agent Layer
+
+| Method | Description |
+|--------|-------------|
+| `plan(req)` | Create tasks, plans, plan steps, update status |
+| `governance(req)` | Create policies, set safety budgets, request/resolve approvals |
+| `execution(req)` | Track execution lifecycle and register agents |
+
+### CRUD
+
+| Method | Description |
+|--------|-------------|
+| `getNode(uid)` | Get a node by UID |
+| `addNode({ label, node_type?, props?, agent_id? })` | Add a generic node |
+| `updateNode(uid, { label?, summary?, confidence?, salience? })` | Update node fields |
+| `deleteNode(uid)` | Tombstone a node and all connected edges |
+| `addLink({ from_uid, to_uid, edge_type, agent_id? })` | Add a typed edge |
+| `getEdges({ from_uid?, to_uid? })` | Get edges by source or target |
+
+### Search
+
+| Method | Description |
+|--------|-------------|
+| `search(query, { node_type?, layer?, limit? })` | Full-text search |
+| `hybridSearch(query, { k?, node_types?, layer? })` | BM25 + vector search with rank fusion |
+
+### Traversal
+
+| Method | Description |
+|--------|-------------|
+| `reasoningChain(uid, maxDepth?)` | Follow epistemic edges from a node |
+| `neighborhood(uid, maxDepth?)` | Get all nodes within N hops |
+
+### Cross-cutting
+
+| Method | Description |
+|--------|-------------|
+| `retrieve(req)` | Unified retrieval: text search, active goals, open questions, weak claims |
+| `traverse(req)` | Graph traversal: chain, neighborhood, path, or subgraph |
+| `evolve(req)` | Lifecycle mutations: update, tombstone, restore, decay, history |
+
+### Health & Stats
+
+| Method | Description |
+|--------|-------------|
+| `health()` | Health check |
+| `stats()` | Graph-wide statistics |
+
+## Error Handling
+
+All methods throw `MindGraphError` on HTTP errors:
+
+```typescript
+import { MindGraphError } from "mindgraph";
+
+try {
+  await graph.getNode("nonexistent");
+} catch (err) {
+  if (err instanceof MindGraphError) {
+    console.error(err.status, err.body);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,393 @@
+interface GraphNode {
+    uid: string;
+    label: string;
+    summary: string;
+    node_type: string;
+    layer: string;
+    confidence: number;
+    salience: number;
+    props: Record<string, unknown>;
+    created_at: number;
+    updated_at: number;
+    tombstone_at: number | null;
+}
+interface GraphEdge {
+    uid: string;
+    from_uid: string;
+    to_uid: string;
+    edge_type: string;
+    layer: string;
+    weight: number;
+    props: Record<string, unknown>;
+    created_at: number;
+    updated_at: number;
+    tombstone_at: number | null;
+}
+interface SearchResult {
+    uid: string;
+    label: string;
+    summary: string;
+    node_type: string;
+    score: number;
+}
+interface PathStep {
+    uid: string;
+    label: string;
+    node_type: string;
+    edge_type: string | null;
+    depth: number;
+    parent_uid: string | null;
+}
+interface IngestRequest {
+    action: "source" | "snippet" | "observation";
+    label: string;
+    content: string;
+    source_uid?: string;
+    medium?: string;
+    url?: string;
+    timestamp?: number;
+    confidence?: number;
+    salience?: number;
+    agent_id?: string;
+}
+interface EntityRequest {
+    action: "create" | "alias" | "resolve" | "fuzzy_resolve" | "merge" | "relate";
+    label?: string;
+    entity_type?: string;
+    text?: string;
+    canonical_uid?: string;
+    alias_score?: number;
+    keep_uid?: string;
+    merge_uid?: string;
+    limit?: number;
+    source_uid?: string;
+    target_uid?: string;
+    edge_type?: string;
+    agent_id?: string;
+}
+interface ArgumentRequest {
+    claim: {
+        label: string;
+        content: string;
+        confidence?: number;
+    };
+    evidence?: {
+        label: string;
+        description: string;
+        evidence_type?: string;
+    }[];
+    warrant?: {
+        label: string;
+        principle: string;
+    };
+    argument?: {
+        label: string;
+        summary: string;
+    };
+    refutes_uid?: string;
+    extends_uid?: string;
+    source_uids?: string[];
+    agent_id?: string;
+}
+interface InquiryRequest {
+    action: "hypothesis" | "theory" | "paradigm" | "anomaly" | "assumption" | "question" | "open_question";
+    label: string;
+    content: string;
+    status?: string;
+    anomalous_to_uid?: string;
+    assumes_uid?: string[];
+    tests_uid?: string;
+    addresses_uid?: string;
+    confidence?: number;
+    salience?: number;
+    related_uids?: string[];
+    agent_id?: string;
+}
+interface StructureRequest {
+    action: "concept" | "pattern" | "mechanism" | "model" | "model_evaluation" | "analogy" | "inference_chain" | "reasoning_strategy" | "sensitivity_analysis" | "theorem" | "equation";
+    label: string;
+    content: string;
+    summary?: string;
+    analogous_to_uid?: string;
+    transfers_to_uid?: string[];
+    evaluates_uid?: string;
+    outperforms_uid?: string;
+    chain_steps?: string[];
+    derived_from_uid?: string[];
+    proven_by_uid?: string;
+    related_uids?: string[];
+    confidence?: number;
+    agent_id?: string;
+}
+interface CommitmentRequest {
+    action: "goal" | "project" | "milestone";
+    label: string;
+    description: string;
+    priority?: string;
+    status?: string;
+    parent_uid?: string;
+    due_date?: number;
+    motivated_by_uid?: string[];
+    agent_id?: string;
+}
+interface DeliberationRequest {
+    action: "open_decision" | "add_option" | "add_constraint" | "resolve" | "get_open";
+    label?: string;
+    description?: string;
+    decision_uid?: string;
+    chosen_option_uid?: string;
+    resolution_rationale?: string;
+    constraint_type?: string;
+    blocks_uid?: string;
+    informs_uid?: string[];
+    agent_id?: string;
+}
+interface ProcedureRequest {
+    action: "create_flow" | "add_step" | "add_affordance" | "add_control";
+    label: string;
+    description?: string;
+    flow_uid?: string;
+    step_order?: number;
+    previous_step_uid?: string;
+    affordance_type?: string;
+    control_type?: string;
+    uses_affordance_uids?: string[];
+    goal_uid?: string;
+    agent_id?: string;
+}
+interface RiskRequest {
+    action: "assess" | "get_assessments";
+    label?: string;
+    description?: string;
+    assessed_uid?: string;
+    severity?: string;
+    likelihood?: number;
+    mitigations?: string[];
+    residual_risk?: number;
+    filter_uid?: string;
+    agent_id?: string;
+}
+interface SessionRequest {
+    action: "open" | "trace" | "close";
+    label?: string;
+    focus?: string;
+    session_uid?: string;
+    trace_content?: string;
+    trace_type?: string;
+    relevant_node_uids?: string[];
+    agent_id?: string;
+}
+interface DistillRequest {
+    label: string;
+    content: string;
+    summarizes_uids?: string[];
+    session_uid?: string;
+    importance?: number;
+    agent_id?: string;
+}
+interface MemoryConfigRequest {
+    action: "set_preference" | "get_preferences" | "set_policy" | "get_policies";
+    label?: string;
+    key?: string;
+    value?: string;
+    policy_content?: string;
+    agent_id?: string;
+}
+interface PlanRequest {
+    action: "create_task" | "create_plan" | "add_step" | "update_status" | "get_plan";
+    label?: string;
+    description?: string;
+    goal_uid?: string;
+    task_uid?: string;
+    plan_uid?: string;
+    step_order?: number;
+    depends_on_uids?: string[];
+    target_uid?: string;
+    status?: string;
+    related_uids?: string[];
+    agent_id?: string;
+}
+interface GovernanceRequest {
+    action: "create_policy" | "set_budget" | "request_approval" | "resolve_approval" | "get_pending";
+    label?: string;
+    policy_content?: string;
+    budget_type?: string;
+    budget_limit?: number;
+    governed_uid?: string;
+    approval_uid?: string;
+    approved?: boolean;
+    resolution_note?: string;
+    requires_plan_uid?: string;
+    approval_request?: string;
+    agent_id?: string;
+}
+interface ExecutionRequest {
+    action: "start" | "complete" | "fail" | "register_agent" | "get_executions";
+    label?: string;
+    plan_uid?: string;
+    executor_uid?: string;
+    execution_uid?: string;
+    outcome?: string;
+    produces_node_uid?: string;
+    error_description?: string;
+    agent_name?: string;
+    agent_role?: string;
+    filter_plan_uid?: string;
+    related_uids?: string[];
+    agent_id?: string;
+}
+interface RetrieveRequest {
+    action: "text" | "semantic" | "hybrid" | "active_goals" | "open_questions" | "weak_claims" | "pending_approvals" | "unresolved_contradictions" | "layer" | "recent";
+    query?: string;
+    k?: number;
+    threshold?: number;
+    layer?: string;
+    node_types?: string[];
+    confidence_min?: number;
+    salience_min?: number;
+    limit?: number;
+    offset?: number;
+}
+interface TraverseRequest {
+    action: "chain" | "neighborhood" | "path" | "subgraph";
+    start_uid: string;
+    end_uid?: string;
+    max_depth?: number;
+    direction?: "outgoing" | "incoming" | "both";
+    edge_types?: string[];
+    weight_threshold?: number;
+}
+interface EvolveRequest {
+    action: "update" | "tombstone" | "restore" | "decay" | "history" | "snapshot" | "tombstone_edge" | "restore_edge" | "tombstone_cascade";
+    uid: string;
+    label?: string;
+    summary?: string;
+    confidence?: number;
+    salience?: number;
+    props_patch?: Record<string, unknown>;
+    reason?: string;
+    cascade?: boolean;
+    half_life_secs?: number;
+    min_salience?: number;
+    min_age_secs?: number;
+    version?: number;
+    agent_id?: string;
+}
+interface SignupRequest {
+    email: string;
+    password: string;
+}
+interface LoginRequest {
+    email: string;
+    password: string;
+}
+interface CreateOrgRequest {
+    name: string;
+    slug?: string;
+}
+interface CreateApiKeyRequest {
+    name?: string;
+}
+interface ApiKeyResponse {
+    id: string;
+    key: string;
+    name: string;
+    prefix: string;
+}
+interface MindGraphConfig {
+    baseUrl: string;
+    apiKey?: string;
+    jwt?: string;
+}
+
+declare class MindGraphError extends Error {
+    status: number;
+    body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+declare class MindGraph {
+    private baseUrl;
+    private headers;
+    constructor(config: MindGraphConfig);
+    private request;
+    private get;
+    private post;
+    private patch;
+    private del;
+    health(): Promise<{
+        status: string;
+    }>;
+    stats(): Promise<Record<string, unknown>>;
+    ingest(req: IngestRequest): Promise<unknown>;
+    entity(req: EntityRequest): Promise<unknown>;
+    /** Convenience: create or find an entity by label. */
+    findOrCreateEntity(label: string, entityType?: string, agentId?: string): Promise<GraphNode & {
+        created: boolean;
+    }>;
+    argue(req: ArgumentRequest): Promise<unknown>;
+    inquire(req: InquiryRequest): Promise<unknown>;
+    structure(req: StructureRequest): Promise<unknown>;
+    commit(req: CommitmentRequest): Promise<unknown>;
+    deliberate(req: DeliberationRequest): Promise<unknown>;
+    procedure(req: ProcedureRequest): Promise<unknown>;
+    risk(req: RiskRequest): Promise<unknown>;
+    session(req: SessionRequest): Promise<unknown>;
+    distill(req: DistillRequest): Promise<unknown>;
+    memoryConfig(req: MemoryConfigRequest): Promise<unknown>;
+    plan(req: PlanRequest): Promise<unknown>;
+    governance(req: GovernanceRequest): Promise<unknown>;
+    execution(req: ExecutionRequest): Promise<unknown>;
+    retrieve(req: RetrieveRequest): Promise<unknown>;
+    traverse(req: TraverseRequest): Promise<unknown>;
+    evolve(req: EvolveRequest): Promise<unknown>;
+    getNode(uid: string): Promise<GraphNode>;
+    addNode(body: {
+        label: string;
+        node_type?: string;
+        props?: Record<string, unknown>;
+        agent_id?: string;
+    }): Promise<GraphNode>;
+    updateNode(uid: string, body: {
+        label?: string;
+        summary?: string;
+        confidence?: number;
+        salience?: number;
+        agent_id?: string;
+    }): Promise<GraphNode>;
+    deleteNode(uid: string): Promise<void>;
+    addLink(body: {
+        from_uid: string;
+        to_uid: string;
+        edge_type: string;
+        agent_id?: string;
+    }): Promise<unknown>;
+    getEdges(params: {
+        from_uid?: string;
+        to_uid?: string;
+    }): Promise<GraphEdge[]>;
+    search(query: string, opts?: {
+        node_type?: string;
+        layer?: string;
+        limit?: number;
+    }): Promise<SearchResult[]>;
+    /** Hybrid BM25 + vector search with reciprocal rank fusion. */
+    hybridSearch(query: string, opts?: {
+        k?: number;
+        node_types?: string[];
+        layer?: string;
+    }): Promise<SearchResult[]>;
+    reasoningChain(uid: string, maxDepth?: number): Promise<PathStep[]>;
+    neighborhood(uid: string, maxDepth?: number): Promise<PathStep[]>;
+    tombstone(uid: string, reason?: string, agentId?: string): Promise<unknown>;
+    restore(uid: string, agentId?: string): Promise<unknown>;
+    signup(email: string, password: string): Promise<unknown>;
+    login(email: string, password: string): Promise<unknown>;
+    createApiKey(name?: string): Promise<ApiKeyResponse>;
+    listApiKeys(): Promise<{
+        api_keys: unknown[];
+    }>;
+    revokeApiKey(id: string): Promise<void>;
+    getUsage(): Promise<unknown>;
+}
+
+export { type ApiKeyResponse, type ArgumentRequest, type CommitmentRequest, type CreateApiKeyRequest, type CreateOrgRequest, type DeliberationRequest, type DistillRequest, type EntityRequest, type EvolveRequest, type ExecutionRequest, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestRequest, type InquiryRequest, type LoginRequest, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type PathStep, type PlanRequest, type ProcedureRequest, type RetrieveRequest, type RiskRequest, type SearchResult, type SessionRequest, type SignupRequest, type StructureRequest, type TraverseRequest };