@datagrout/conduit 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -461,6 +461,203 @@ interface MCPPrompt {
     }>;
 }
 
+/**
+ * Prism namespace — data transformation, charting, rendering, and export.
+ */
+
+declare class PrismNamespace {
+    private callDg;
+    private warn;
+    /** @internal */
+    constructor(callDg: (tool: string, params: Record<string, any>) => Promise<any>, warn: (method: string) => void);
+    /** AI-driven data transformation (`data-grout/prism.refract`). */
+    refract(options: RefractOptions): Promise<any>;
+    /** AI-driven charting (`data-grout/prism.chart`). */
+    chart(options: ChartOptions): Promise<any>;
+    /** Generate a document toward a natural-language goal (`data-grout/prism.render`). */
+    render(options: {
+        goal: string;
+        payload?: any;
+        format?: string;
+        sections?: any[];
+        [k: string]: any;
+    }): Promise<any>;
+    /** Convert content to another format without LLM (`data-grout/prism.export`). */
+    export(options: {
+        content: any;
+        format: string;
+        style?: Record<string, any>;
+        metadata?: Record<string, any>;
+        [k: string]: any;
+    }): Promise<any>;
+    /** Semantic type transformation (`data-grout/prism.focus`). */
+    focus(options: PrismFocusOptions): Promise<any>;
+}
+
+/**
+ * Logic Cell namespace — agent memory, facts, constraints, and hypotheticals.
+ */
+
+declare class LogicNamespace {
+    private callDg;
+    private warn;
+    /** @internal */
+    constructor(callDg: (tool: string, params: Record<string, any>) => Promise<any>, warn: (method: string) => void);
+    /** Assert facts into the logic cell (`data-grout/logic.remember`). */
+    remember(statement: string, options?: RememberOptions): Promise<{
+        handles: string[];
+        facts: any[];
+        count: number;
+        message: string;
+    }>;
+    remember(options: RememberOptions): Promise<{
+        handles: string[];
+        facts: any[];
+        count: number;
+        message: string;
+    }>;
+    /** Query the logic cell with natural language (`data-grout/logic.query`). */
+    query(question: string, options?: QueryCellOptions): Promise<{
+        results: any[];
+        total: number;
+        description: string;
+        message: string;
+    }>;
+    query(options: QueryCellOptions): Promise<{
+        results: any[];
+        total: number;
+        description: string;
+        message: string;
+    }>;
+    /** Retract facts from the logic cell (`data-grout/logic.forget`). */
+    forget(options: ForgetOptions): Promise<{
+        retracted: number;
+        handles: string[];
+        message: string;
+    }>;
+    /** Reflect on the logic cell (`data-grout/logic.reflect`). */
+    reflect(options?: ReflectOptions): Promise<{
+        total: number;
+        summary?: any;
+        entity?: string;
+        facts?: any[];
+        message: string;
+    }>;
+    /** Add a constraint rule (`data-grout/logic.constrain`). */
+    constrain(rule: string, options?: ConstrainOptions): Promise<{
+        handle: string;
+        name: string;
+        rule: string;
+        message: string;
+    }>;
+    /** Hydrate the logic cell from external data (`data-grout/logic.hydrate`). */
+    hydrate(params: Record<string, any>): Promise<any>;
+    /** Export the logic cell contents (`data-grout/logic.export`). */
+    exportCell(params?: Record<string, any>): Promise<any>;
+    /** Import facts into the logic cell (`data-grout/logic.import`). */
+    importCell(params: Record<string, any>): Promise<any>;
+    /** Tabulate logic cell contents (`data-grout/logic.tabulate`). */
+    tabulate(params?: Record<string, any>): Promise<any>;
+    /** Manage hypothetical worlds (`data-grout/logic.worlds`). */
+    worlds(params: Record<string, any>): Promise<any>;
+}
+
+/**
+ * Warden namespace — safety checks, intent verification, and consensus.
+ */
+declare class WardenNamespace {
+    private callDg;
+    private warn;
+    /** @internal */
+    constructor(callDg: (tool: string, params: Record<string, any>) => Promise<any>, warn: (method: string) => void);
+    /** Run a canary safety check (`data-grout/warden.canary`). */
+    canary(params: Record<string, any>): Promise<any>;
+    /** Verify intent before executing an action (`data-grout/warden.intent`). */
+    verifyIntent(params: Record<string, any>): Promise<any>;
+    /** Adjudicate a dispute or ambiguity (`data-grout/warden.adjudicate`). */
+    adjudicate(params: Record<string, any>): Promise<any>;
+    /** Multi-model ensemble consensus check (`data-grout/warden.ensemble`). */
+    ensemble(params: Record<string, any>): Promise<any>;
+}
+
+/**
+ * Deliverables namespace — work product tracking and retrieval.
+ */
+declare class DeliverablesNamespace {
+    private callDg;
+    private warn;
+    /** @internal */
+    constructor(callDg: (tool: string, params: Record<string, any>) => Promise<any>, warn: (method: string) => void);
+    /** Register a work product (`data-grout/deliverables.register`). */
+    register(params: Record<string, any>): Promise<any>;
+    /** List deliverables with optional semantic search (`data-grout/deliverables.list`). */
+    list(params?: Record<string, any>): Promise<any>;
+    /** Get a specific deliverable by reference (`data-grout/deliverables.get`). */
+    get(refId: string): Promise<any>;
+}
+
+/**
+ * Ephemerals namespace — cache management and inspection.
+ */
+declare class EphemeralsNamespace {
+    private callDg;
+    private warn;
+    /** @internal */
+    constructor(callDg: (tool: string, params: Record<string, any>) => Promise<any>, warn: (method: string) => void);
+    /** List cached results (`data-grout/ephemerals.list`). */
+    list(params?: Record<string, any>): Promise<any>;
+    /** Inspect a specific cache entry (`data-grout/ephemerals.inspect`). */
+    inspect(cacheRef: string): Promise<any>;
+}
+
+/**
+ * Flow namespace — orchestration, routing, approvals, and execution history.
+ */
+
+declare class FlowNamespace {
+    private callDg;
+    private warn;
+    /** @internal */
+    constructor(callDg: (tool: string, params: Record<string, any>) => Promise<any>, warn: (method: string) => void);
+    /** Execute a multi-step workflow plan (`data-grout/flow.into`). */
+    run(options: FlowOptions): Promise<any>;
+    /** Conditional dispatch with predicate-based branching (`data-grout/flow.route`). */
+    route(options: {
+        branches: Array<Record<string, any>>;
+        payload?: any;
+        cacheRef?: string;
+        else?: any;
+        [k: string]: any;
+    }): Promise<any>;
+    /** Pause workflow for human approval (`data-grout/flow.request-approval`). */
+    requestApproval(options: {
+        action: string;
+        details?: Record<string, any>;
+        reason?: string;
+        context?: Record<string, any>;
+        [k: string]: any;
+    }): Promise<any>;
+    /** Request user clarification for missing fields (`data-grout/flow.request-feedback`). */
+    requestFeedback(options: {
+        missing_fields: string[];
+        reason: string;
+        current_data?: Record<string, any>;
+        suggestions?: Record<string, any>;
+        context?: Record<string, any>;
+        [k: string]: any;
+    }): Promise<any>;
+    /** List recent tool executions (`data-grout/inspect.execution-history`). */
+    history(options?: {
+        limit?: number;
+        offset?: number;
+        status?: string;
+        refractions_only?: boolean;
+        [k: string]: any;
+    }): Promise<any>;
+    /** Get details for a specific execution (`data-grout/inspect.execution-details`). */
+    details(executionId: string): Promise<any>;
+}
+
 /**
  * Stateful guided workflow session returned by `Client.guide()`.
  *
@@ -583,6 +780,19 @@ declare class Client {
      * `maxRetries` times with 500ms backoff between attempts.
      */
     private sendWithRetry;
+    private callDgTool;
+    /** Data transformation, charting, rendering, and type bridging. */
+    get prism(): PrismNamespace;
+    /** Persistent agent memory backed by a Prolog logic cell. */
+    get logic(): LogicNamespace;
+    /** Safety gates, intent verification, and multi-model consensus. */
+    get warden(): WardenNamespace;
+    /** Work product registration, listing, and retrieval. */
+    get deliverables(): DeliverablesNamespace;
+    /** Cache listing and inspection. */
+    get ephemerals(): EphemeralsNamespace;
+    /** Multi-step orchestration, routing, approvals, and execution history. */
+    get flow(): FlowNamespace;
     /**
      * List all tools exposed by the connected MCP server.
      *
@@ -691,32 +901,6 @@ declare class Client {
      * @param options.choice    - Option ID selected at the current step.
      */
     guide(options: GuideRequestOptions): Promise<GuidedSession>;
-    /**
-     * Execute a pre-planned sequence of tool calls (a "flow") through the
-     * DataGrout gateway.
-     *
-     * JSON-RPC method: `tools/call` → `data-grout/flow.into`
-     *
-     * @param options.plan          - Ordered list of tool call descriptors.
-     * @param options.validateCtc   - Validate each call against its CTC schema (default: `true`).
-     * @param options.saveAsSkill   - Persist the flow as a reusable skill (default: `false`).
-     * @param options.inputData     - Runtime input data for the flow.
-     */
-    flowInto(options: FlowOptions): Promise<any>;
-    /**
-     * Transform data from one annotated type to another using the DataGrout
-     * Prism semantic mapping engine.
-     *
-     * JSON-RPC method: `tools/call` → `data-grout/prism.focus`
-     *
-     * @param options.data               - Source payload to transform.
-     * @param options.sourceType         - Semantic type of the source data.
-     * @param options.targetType         - Desired semantic type for the output.
-     * @param options.sourceAnnotations  - Additional schema hints for the source.
-     * @param options.targetAnnotations  - Additional schema hints for the target.
-     * @param options.context            - Free-text context to guide the mapping.
-     */
-    prismFocus(options: PrismFocusOptions): Promise<any>;
     /**
      * Generate an execution plan for a goal using DataGrout's planning engine.
      *
@@ -737,89 +921,6 @@ declare class Client {
      * @param options.modelOverrides      - Override LLM model settings.
      */
     plan(options: PlanOptions): Promise<any>;
-    /**
-     * Analyse and summarise a payload using the DataGrout Prism refraction engine.
-     *
-     * JSON-RPC method: `tools/call` → `data-grout/prism.refract`
-     *
-     * @param options.goal    - Description of what to extract or summarise.
-     * @param options.payload - Input data to analyse (any JSON-serializable value).
-     * @param options.verbose - Include detailed processing trace in the response.
-     * @param options.chart   - Also generate a chart representation.
-     */
-    refract(options: RefractOptions): Promise<any>;
-    /**
-     * Generate a chart from a data payload using the DataGrout Prism engine.
-     *
-     * JSON-RPC method: `tools/call` → `data-grout/prism.chart`
-     *
-     * @param options.goal      - What the chart should visualise.
-     * @param options.payload   - Input data (any JSON-serializable value).
-     * @param options.format    - Output format (e.g. `"png"`, `"svg"`).
-     * @param options.chartType - Chart type (e.g. `"bar"`, `"line"`, `"pie"`).
-     * @param options.title     - Chart title.
-     * @param options.xLabel    - X-axis label.
-     * @param options.yLabel    - Y-axis label.
-     * @param options.width     - Chart width in pixels.
-     * @param options.height    - Chart height in pixels.
-     */
-    chart(options: ChartOptions): Promise<any>;
-    /**
-     * Generate a document toward a natural-language goal.
-     * Supported formats: markdown, html, pdf, json.
-     */
-    render(options: {
-        goal: string;
-        payload?: any;
-        format?: string;
-        sections?: any[];
-        [k: string]: any;
-    }): Promise<any>;
-    /**
-     * Convert content to another format (no LLM). Supports csv, xlsx, pdf, json, html, markdown, etc.
-     */
-    export(options: {
-        content: any;
-        format: string;
-        style?: Record<string, any>;
-        metadata?: Record<string, any>;
-        [k: string]: any;
-    }): Promise<any>;
-    /**
-     * Pause workflow for human approval. Use for destructive or policy-gated actions.
-     */
-    requestApproval(options: {
-        action: string;
-        details?: Record<string, any>;
-        reason?: string;
-        context?: Record<string, any>;
-        [k: string]: any;
-    }): Promise<any>;
-    /**
-     * Request user clarification for missing fields. Pauses until user provides values.
-     */
-    requestFeedback(options: {
-        missing_fields: string[];
-        reason: string;
-        current_data?: Record<string, any>;
-        suggestions?: Record<string, any>;
-        context?: Record<string, any>;
-        [k: string]: any;
-    }): Promise<any>;
-    /**
-     * List recent tool executions for the current server.
-     */
-    executionHistory(options?: {
-        limit?: number;
-        offset?: number;
-        status?: string;
-        refractions_only?: boolean;
-        [k: string]: any;
-    }): Promise<any>;
-    /**
-     * Get details and transcript for a specific execution.
-     */
-    executionDetails(executionId: string): Promise<any>;
     /**
      * Call any DataGrout first-party tool by its short name.
      *
@@ -832,121 +933,6 @@ declare class Client {
      * @param params        - Tool input arguments.
      */
     dg(toolShortName: string, params?: Record<string, any>): Promise<any>;
-    /**
-     * Store facts in the agent's persistent logic cell.
-     *
-     * Converts natural language to symbolic facts and stores them
-     * durably across sessions. Accepts either a natural language `statement`
-     * (positional or via options) or a pre-structured `facts` array.
-     *
-     * Throws `InvalidConfigError` if neither `statement` nor `facts` is provided.
-     *
-     * JSON-RPC method: `tools/call` → `data-grout/logic.remember`
-     *
-     * @param statement - Natural language statement to remember.
-     * @param options.tag   - Tag/namespace for grouping facts (default: `"default"`).
-     * @param options.facts - Optional pre-structured fact list (skips NL conversion).
-     */
-    remember(statement: string, options?: RememberOptions): Promise<{
-        handles: string[];
-        facts: any[];
-        count: number;
-        message: string;
-    }>;
-    /**
-     * Store facts in the agent's persistent logic cell using an options object.
-     *
-     * Throws `InvalidConfigError` if neither `statement` nor `facts` is provided.
-     *
-     * JSON-RPC method: `tools/call` → `data-grout/logic.remember`
-     */
-    remember(options: RememberOptions): Promise<{
-        handles: string[];
-        facts: any[];
-        count: number;
-        message: string;
-    }>;
-    /**
-     * Query the agent's logic cell with a natural language question.
-     *
-     * Translates the question to query patterns and retrieves matching facts.
-     * Accepts either a natural language `question` (positional or via options)
-     * or a pre-built `patterns` array.
-     *
-     * Throws `InvalidConfigError` if neither `question` nor `patterns` is provided.
-     *
-     * JSON-RPC method: `tools/call` → `data-grout/logic.query`
-     *
-     * @param question       - Natural language question.
-     * @param options.limit  - Maximum results to return (default: 50).
-     * @param options.patterns - Optional pre-built pattern list (skips NL translation).
-     */
-    queryCell(question: string, options?: QueryCellOptions): Promise<{
-        results: any[];
-        total: number;
-        description: string;
-        message: string;
-    }>;
-    /**
-     * Query the agent's logic cell using an options object.
-     *
-     * Throws `InvalidConfigError` if neither `question` nor `patterns` is provided.
-     *
-     * JSON-RPC method: `tools/call` → `data-grout/logic.query`
-     */
-    queryCell(options: QueryCellOptions): Promise<{
-        results: any[];
-        total: number;
-        description: string;
-        message: string;
-    }>;
-    /**
-     * Retract facts from the agent's logic cell.
-     *
-     * Throws `InvalidConfigError` if neither `handles` nor `pattern` is provided.
-     *
-     * JSON-RPC method: `tools/call` → `data-grout/logic.forget`
-     *
-     * @param options.handles - Specific fact handles to retract.
-     * @param options.pattern - Natural language pattern — retract all matching facts.
-     */
-    forget(options: ForgetOptions): Promise<{
-        retracted: number;
-        handles: string[];
-        message: string;
-    }>;
-    /**
-     * Reflect on the agent's logic cell — returns a full snapshot or a
-     * per-entity view of all stored facts.
-     *
-     * JSON-RPC method: `tools/call` → `data-grout/logic.reflect`
-     *
-     * @param options.entity      - Optional entity name to scope reflection.
-     * @param options.summaryOnly - When `true`, return only counts (default: `false`).
-     */
-    reflect(options?: ReflectOptions): Promise<{
-        total: number;
-        summary?: any;
-        entity?: string;
-        facts?: any[];
-        message: string;
-    }>;
-    /**
-     * Store a logical rule or policy in the agent's logic cell.
-     *
-     * Rules are permanent constraints evaluated during `queryCell()` calls.
-     *
-     * JSON-RPC method: `tools/call` → `data-grout/logic.constrain`
-     *
-     * @param rule         - Natural language rule (e.g. `"VIP customers have ARR > $500K"`).
-     * @param options.tag  - Tag/namespace for this constraint (default: `"constraint"`).
-     */
-    constrain(rule: string, options?: ConstrainOptions): Promise<{
-        handle: string;
-        name: string;
-        rule: string;
-        message: string;
-    }>;
     /**
      * Estimate the credit cost of a tool call without executing it.
      *