@punica/editor 1.0.5 → 1.0.7

package/types/punica.module.flow.mcp.d.ts

@@ -0,0 +1,26 @@
+declare module 'punica' {
+  /**
+   * IvyNode → MCP server integration metadata (flow-node manifest extension).
+   *
+   * This interface describes how a flow node declares that it talks to an
+   * MCP server. It lives in `ivy.node.json` manifests as
+   * `manifest.mcpMetadata` and is used by the flow engine to wire up
+   * node execution against an MCP tool endpoint.
+   *
+   * **Not** the MCP runtime client API — for that see
+   * `punica.module.runtime.mcp.d.ts` (`runtime.mcp.McpApi`).
+   */
+  export interface IvyMcpMetadata {
+    id: string;
+    name: string;
+    version?: string;
+    /** MCP method / route name. */
+    method?: string;
+    /** HTTP or protocol-level information if relevant. */
+    endpoint?: string;
+    /** Optional schema or contract representation. */
+    schema?: JSONObject;
+    /** Additional configuration for the MCP integration. */
+    config?: JSONObject;
+  }
+}

package/types/punica.module.flow.notebook.d.ts

@@ -0,0 +1,210 @@
+declare module 'punica' {
+  /**
+   * Base JSON / Notebook types
+   * These are adapted from the IPython notebook (nbformat 4.x) specification
+   * and extended with Ivy-specific metadata.
+   */
+
+  export type JSONPrimitive = string | number | boolean | null;
+
+  export type JSONValue =
+    | JSONPrimitive
+    | JSONValue[]
+    | { [key: string]: JSONValue };
+
+  export interface JSONObject {
+    [key: string]: JSONValue;
+  }
+
+  export type CellType = 'code' | 'markdown' | 'raw';
+
+  /**
+   * Canonical multiline representation used in nbformat.
+   */
+  export type MultilineString = string | string[];
+
+  /**
+   * Rich output mime bundle.
+   */
+  export type MimeBundle = Record<string, JSONValue>;
+
+  export type Attachments = Record<string, MimeBundle>;
+
+  /**
+   * Cell-level metadata extended with Ivy namespaces.
+   * Cells can have their own ivy.node metadata (for individual cell capabilities).
+   *
+   * Note:
+   * - We intentionally do NOT extend JSONObject here, because `ivy.node` is a
+   *   rich TypeScript object (`IvyNodeMetadata`) rather than a strict JSONValue.
+   * - The index signature still enforces JSONValue for arbitrary metadata keys,
+   *   but well-known fields like `ivy` are allowed to be richer objects.
+   */
+  export interface CellMetadata {
+    /**
+     * Ivy-specific metadata for this cell.
+     * When present, this cell represents an Ivy node with capability definition.
+     */
+    ivy?: {
+      /**
+       * Ivy node metadata for this cell.
+       * Defines the capability this cell represents.
+       */
+      node?: IvyNodeMetadata;
+      /**
+       * Cell role for IvyNode v0.1 execution model.
+       * - 'input': First cell that receives input data (runner injects __ivy_input__)
+       * - 'compute': Intermediate cells that perform computation
+       * - 'output': Last cell that produces output (runner reads __ivy_output__)
+       */
+      cell?: {
+        role?: 'input' | 'compute' | 'output';
+      };
+      /**
+       * Allow additional Ivy sub-namespaces or view data.
+       * We use `unknown` here to avoid over-constraining richer objects.
+       */
+      [key: string]: unknown;
+    };
+    /**
+     * Workflow-related metadata (for workflow serialization).
+     */
+    workflowNodeId?: string;
+    workflowNodeType?: string;
+    label?: string;
+    disabled?: boolean;
+    /**
+     * Additional arbitrary metadata fields.
+     * Typed as unknown to allow richer, non-JSONValue objects when needed.
+     */
+    [key: string]: unknown;
+  }
+
+  /**
+   * Base cell for all notebook cell types.
+   */
+  export interface BaseCell {
+    id: string;
+    cell_type: CellType;
+    metadata: CellMetadata;
+    source: MultilineString;
+  }
+
+  export interface MarkdownCell extends BaseCell {
+    cell_type: 'markdown';
+    attachments?: Attachments;
+  }
+
+  export interface RawCell extends BaseCell {
+    cell_type: 'raw';
+    attachments?: Attachments;
+  }
+
+  export interface CodeCell extends BaseCell {
+    cell_type: 'code';
+    execution_count: number | null;
+    outputs: Output[];
+  }
+
+  export type NotebookCell = CodeCell | MarkdownCell | RawCell;
+
+  /**
+   * Standard nbformat outputs extended with Ivy-specific fields.
+   */
+  export interface BaseOutput {
+    metadata?: JSONObject;
+  }
+
+  export interface StreamOutput extends BaseOutput {
+    output_type: 'stream';
+    name: 'stdout' | 'stderr';
+    text: MultilineString;
+  }
+
+  export interface DisplayDataOutput extends BaseOutput {
+    output_type: 'display_data';
+    data: MimeBundle;
+  }
+
+  export interface ExecuteResultOutput extends BaseOutput {
+    output_type: 'execute_result';
+    data: MimeBundle;
+    execution_count: number;
+  }
+
+  export interface ErrorOutput extends BaseOutput {
+    output_type: 'error';
+    ename: string;
+    evalue: string;
+    traceback: string[];
+  }
+
+  /**
+   * Extended / generic output shape that allows Ivy runtimes
+   * to attach richer execution state.
+   */
+  export interface ExtendedOutput extends BaseOutput {
+    output_type: string;
+    status?: 'ok' | 'error';
+    comm_id?: string;
+    method?: string;
+    execution_state?: string;
+    name?: string;
+    text?: MultilineString;
+    value?: JSONValue;
+    title?: string;
+    isDone?: boolean;
+    // Allow Ivy-specific fields without losing type safety.
+    [key: string]: JSONValue | undefined;
+  }
+
+  export type Output =
+    | StreamOutput
+    | DisplayDataOutput
+    | ExecuteResultOutput
+    | ErrorOutput
+    | ExtendedOutput;
+
+  export interface Kernelspec {
+    name: string;
+    display_name?: string;
+    language?: string;
+  }
+
+  export interface LanguageInfo {
+    name: string;
+    version?: string;
+    file_extension?: string;
+    mimetype?: string;
+    nbconvert_exporter?: string;
+    pygments_lexer?: string;
+    codemirror_mode?: string | { name: string; version?: number };
+  }
+
+  /**
+   * Notebook-level metadata extended with Ivy namespaces.
+   */
+  export interface NotebookMetadata extends JSONObject {
+    kernelspec?: Kernelspec;
+    language_info?: LanguageInfo;
+    ivy?: {
+      node?: IvyNodeMetadata;
+      flow?: IvyFlowMetadata;
+      agent?: IvyAgentMetadata;
+      mcp?: IvyMcpMetadata;
+      view?: IvyViewMetadata;
+      [key: string]: JSONValue | undefined;
+    };
+  }
+
+  /**
+   * Canonical Ivy notebook representation.
+   * This is nbformat 4.x plus Ivy-specific metadata under metadata.ivy.
+   */
+  export interface IPythonNotebook {
+    cells: NotebookCell[];
+    metadata: NotebookMetadata;
+    nbformat: 4;
+    nbformat_minor: number;
+  }
+}