@morphllm/subagents 0.1.0

package/src/core/types.ts

@@ -0,0 +1,64 @@
+/**
+ * Core types shared across all subagents
+ */
+
+/** Tool definition for OpenAI-compatible APIs */
+export interface Tool {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  };
+}
+
+/** Chat message for conversation history */
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string;
+  name?: string;
+  tool_call_id?: string;
+}
+
+/** Tool call tracking */
+export interface ToolCall {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+  result?: string;
+  error?: string;
+  status: 'pending' | 'running' | 'completed' | 'error';
+}
+
+/** Stream events for real-time UI updates */
+export type StreamEvent =
+  | { type: 'message_start'; message: { role: 'assistant' } }
+  | { type: 'content_delta'; delta: { text: string } }
+  | { type: 'tool_start'; tool: { id: string; name: string; arguments: Record<string, unknown> } }
+  | { type: 'tool_end'; tool: { id: string; result?: string; error?: string } }
+  | { type: 'message_end' }
+  | { type: 'error'; error: string };
+
+/** Agent run result */
+export interface AgentRunResult {
+  response: string;
+  toolCalls: ToolCall[];
+}
+
+/** Base client options */
+export interface BaseClientOptions {
+  /** API base URL */
+  apiUrl?: string;
+  /** Request timeout in milliseconds */
+  timeout?: number;
+}
+
+/** Base agent options */
+export interface BaseAgentOptions extends BaseClientOptions {
+  /** OpenAI-compatible client instance */
+  openai?: any;
+  /** Model to use */
+  model?: string;
+  /** System instructions */
+  instructions?: string;
+}

package/src/docx/agent.ts

@@ -0,0 +1,311 @@
+/**
+ * DocxAgent - AI agent for DOCX document editing
+ *
+ * Uses OpenAI-compatible API to process requests and execute
+ * document editing operations.
+ */
+
+import { BaseAgent } from '../core/base-agent';
+import type { Tool } from '../core/types';
+import { DocxClient } from './client';
+import type { DocxAgentOptions } from './types';
+
+const DEFAULT_INSTRUCTIONS = `You are an expert DOCX document editing assistant.
+
+When editing documents:
+1. First read the document to understand its structure
+2. Use track changes for all modifications
+3. Add comments to flag issues or request clarification
+4. Be precise with paragraph text matching - use unique text snippets
+
+Available tools:
+- read_document: Read the document content
+- add_comment: Add a comment to a specific paragraph
+- insert_text: Insert text within a paragraph (tracked change)
+- propose_deletion: Mark text for deletion (tracked change)
+- reply_comment: Reply to an existing comment
+- resolve_comment: Mark a comment as resolved
+- delete_comment: Delete a comment
+- insert_paragraph: Insert a new paragraph
+- validate_document: Validate DOCX structure`;
+
+const TOOLS: Tool[] = [
+  {
+    type: 'function',
+    function: {
+      name: 'read_document',
+      description: 'Read the document content as plain text',
+      parameters: {
+        type: 'object',
+        properties: {
+          doc_id: { type: 'string', description: 'Document ID' },
+        },
+        required: ['doc_id'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'add_comment',
+      description: 'Add a comment to a specific paragraph in the document',
+      parameters: {
+        type: 'object',
+        properties: {
+          doc_id: { type: 'string', description: 'Document ID' },
+          para_text: { type: 'string', description: 'Unique text from the target paragraph' },
+          comment: { type: 'string', description: 'Comment text to add' },
+          highlight: { type: 'string', description: 'Optional specific text to highlight' },
+        },
+        required: ['doc_id', 'para_text', 'comment'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'insert_text',
+      description: 'Insert text within a paragraph (creates a tracked change)',
+      parameters: {
+        type: 'object',
+        properties: {
+          doc_id: { type: 'string', description: 'Document ID' },
+          para_text: { type: 'string', description: 'Unique text from the target paragraph' },
+          after: { type: 'string', description: 'Text after which to insert' },
+          new_text: { type: 'string', description: 'Text to insert' },
+        },
+        required: ['doc_id', 'para_text', 'after', 'new_text'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'propose_deletion',
+      description: 'Mark text for deletion (creates a tracked change)',
+      parameters: {
+        type: 'object',
+        properties: {
+          doc_id: { type: 'string', description: 'Document ID' },
+          para_text: { type: 'string', description: 'Unique text from the target paragraph' },
+          target: { type: 'string', description: 'Specific text to delete (optional, defaults to whole paragraph)' },
+        },
+        required: ['doc_id', 'para_text'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'reply_comment',
+      description: 'Reply to an existing comment',
+      parameters: {
+        type: 'object',
+        properties: {
+          doc_id: { type: 'string', description: 'Document ID' },
+          comment_id: { type: 'string', description: 'ID of the comment to reply to' },
+          reply: { type: 'string', description: 'Reply text' },
+        },
+        required: ['doc_id', 'comment_id', 'reply'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'resolve_comment',
+      description: 'Mark a comment as resolved',
+      parameters: {
+        type: 'object',
+        properties: {
+          doc_id: { type: 'string', description: 'Document ID' },
+          comment_id: { type: 'string', description: 'ID of the comment to resolve' },
+        },
+        required: ['doc_id', 'comment_id'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'delete_comment',
+      description: 'Delete a comment and its replies',
+      parameters: {
+        type: 'object',
+        properties: {
+          doc_id: { type: 'string', description: 'Document ID' },
+          comment_id: { type: 'string', description: 'ID of the comment to delete' },
+        },
+        required: ['doc_id', 'comment_id'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'insert_paragraph',
+      description: 'Insert a new paragraph after existing text',
+      parameters: {
+        type: 'object',
+        properties: {
+          doc_id: { type: 'string', description: 'Document ID' },
+          after_text: { type: 'string', description: 'Text after which to insert the new paragraph' },
+          new_text: { type: 'string', description: 'Content of the new paragraph' },
+        },
+        required: ['doc_id', 'after_text', 'new_text'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'validate_document',
+      description: 'Validate the document structure',
+      parameters: {
+        type: 'object',
+        properties: {
+          doc_id: { type: 'string', description: 'Document ID' },
+        },
+        required: ['doc_id'],
+      },
+    },
+  },
+];
+
+export class DocxAgent extends BaseAgent<DocxClient> {
+  private documentId?: string;
+
+  constructor(options: DocxAgentOptions = {}) {
+    const client = new DocxClient(options);
+    super({ ...options, client });
+    this.documentId = options.documentId;
+  }
+
+  protected getDefaultModel(): string {
+    return 'moonshot-v1-32k';
+  }
+
+  protected getDefaultInstructions(): string {
+    return this.documentId
+      ? `${DEFAULT_INSTRUCTIONS}\n\nCurrent document ID: ${this.documentId}`
+      : DEFAULT_INSTRUCTIONS;
+  }
+
+  protected getTools(): Tool[] {
+    return TOOLS;
+  }
+
+  /** Set the current document ID */
+  setDocument(docId: string) {
+    this.documentId = docId;
+  }
+
+  /** Get current document ID */
+  getDocumentId(): string | undefined {
+    return this.documentId;
+  }
+
+  protected async executeTool(name: string, args: Record<string, unknown>): Promise<string> {
+    const docId = (args.doc_id as string) || this.documentId;
+
+    if (!docId) {
+      return 'Error: No document ID provided. Please upload a document first.';
+    }
+
+    try {
+      switch (name) {
+        case 'read_document': {
+          const result = await this.client.read(docId);
+          return `Document content (${result.paragraphs} paragraphs):\n\n${result.content}`;
+        }
+
+        case 'add_comment': {
+          const result = await this.client.edit(docId, [
+            {
+              type: 'add_comment',
+              para_text: args.para_text as string,
+              comment: args.comment as string,
+              highlight: args.highlight as string | undefined,
+            },
+          ]);
+          return result.results[0];
+        }
+
+        case 'insert_text': {
+          const result = await this.client.edit(docId, [
+            {
+              type: 'insert_text',
+              para_text: args.para_text as string,
+              after: args.after as string,
+              new_text: args.new_text as string,
+            },
+          ]);
+          return result.results[0];
+        }
+
+        case 'propose_deletion': {
+          const result = await this.client.edit(docId, [
+            {
+              type: 'propose_deletion',
+              para_text: args.para_text as string,
+              target: args.target as string | undefined,
+            },
+          ]);
+          return result.results[0];
+        }
+
+        case 'reply_comment': {
+          const result = await this.client.edit(docId, [
+            {
+              type: 'reply_comment',
+              comment_id: args.comment_id as string,
+              reply: args.reply as string,
+            },
+          ]);
+          return result.results[0];
+        }
+
+        case 'resolve_comment': {
+          const result = await this.client.edit(docId, [
+            {
+              type: 'resolve_comment',
+              comment_id: args.comment_id as string,
+            },
+          ]);
+          return result.results[0];
+        }
+
+        case 'delete_comment': {
+          const result = await this.client.edit(docId, [
+            {
+              type: 'delete_comment',
+              comment_id: args.comment_id as string,
+            },
+          ]);
+          return result.results[0];
+        }
+
+        case 'insert_paragraph': {
+          const result = await this.client.edit(docId, [
+            {
+              type: 'insert_paragraph',
+              after_text: args.after_text as string,
+              new_text: args.new_text as string,
+            },
+          ]);
+          return result.results[0];
+        }
+
+        case 'validate_document': {
+          const result = await this.client.validate(docId);
+          return `${result.result}: ${result.output}`;
+        }
+
+        default:
+          return `Error: Unknown tool '${name}'`;
+      }
+    } catch (error) {
+      return `Error: ${error instanceof Error ? error.message : String(error)}`;
+    }
+  }
+}

package/src/docx/client.ts

@@ -0,0 +1,69 @@
+/**
+ * DocxClient - HTTP client for DOCX document API
+ */
+
+import { BaseClient } from '../core/base-client';
+import type {
+  DocxClientOptions,
+  DocumentInfo,
+  ReadResponse,
+  EditOperation,
+  EditResponse,
+  ValidateResponse,
+} from './types';
+
+const DEFAULT_API_URL = 'https://docx-api-service-production.up.railway.app';
+
+export class DocxClient extends BaseClient {
+  constructor(options: DocxClientOptions = {}) {
+    super(options);
+  }
+
+  protected getDefaultApiUrl(): string {
+    return process.env.DOCX_API_URL || DEFAULT_API_URL;
+  }
+
+  /**
+   * Upload a DOCX document.
+   */
+  async upload(file: File | Blob, filename?: string): Promise<DocumentInfo> {
+    const formData = new FormData();
+    formData.append('file', file, filename || 'document.docx');
+    return this.postFormData('/documents/upload', formData);
+  }
+
+  /**
+   * Download a DOCX document.
+   */
+  async download(docId: string): Promise<Blob> {
+    return this.downloadBlob(`/documents/${docId}`);
+  }
+
+  /**
+   * Read document content as plain text.
+   */
+  async read(docId: string): Promise<ReadResponse> {
+    return this.post(`/documents/${docId}/read`);
+  }
+
+  /**
+   * Execute edit operations on a document.
+   */
+  async edit(docId: string, operations: EditOperation[]): Promise<EditResponse> {
+    return this.post(`/documents/${docId}/edit`, { operations });
+  }
+
+  /**
+   * Validate document structure.
+   */
+  async validate(docId: string): Promise<ValidateResponse> {
+    return this.post(`/documents/${docId}/validate`);
+  }
+
+  /**
+   * Delete a document from storage.
+   */
+  async deleteDocument(docId: string): Promise<void> {
+    return this.delete(`/documents/${docId}`);
+  }
+}

package/src/docx/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @morphllm/subagents/docx
+ *
+ * DOCX document editing subagent for track changes, comments, and more.
+ */
+
+export { DocxClient } from './client';
+export { DocxAgent } from './agent';
+export type {
+  DocumentInfo,
+  ReadResponse,
+  EditOperation,
+  EditOperationType,
+  EditResponse,
+  ValidateResponse,
+  DocxClientOptions,
+  DocxAgentOptions,
+} from './types';

package/src/docx/types.ts

@@ -0,0 +1,68 @@
+/**
+ * Types for DOCX subagent
+ */
+
+import type { BaseClientOptions, BaseAgentOptions } from '../core/types';
+
+/** Document info returned after upload */
+export interface DocumentInfo {
+  doc_id: string;
+  message: string;
+}
+
+/** Response from reading document content */
+export interface ReadResponse {
+  content: string;
+  paragraphs: number;
+}
+
+/** Edit operation types */
+export type EditOperationType =
+  | 'add_comment'
+  | 'reply_comment'
+  | 'resolve_comment'
+  | 'delete_comment'
+  | 'insert_text'
+  | 'insert_paragraph'
+  | 'propose_deletion';
+
+/** Edit operation payload */
+export interface EditOperation {
+  type: EditOperationType;
+  para_text?: string;
+  comment?: string;
+  highlight?: string;
+  context?: string;
+  after?: string;
+  after_text?: string;
+  new_text?: string;
+  target?: string;
+  comment_id?: string;
+  reply?: string;
+  author?: string;
+}
+
+/** Response from edit operations */
+export interface EditResponse {
+  results: string[];
+  doc_id: string;
+}
+
+/** Response from document validation */
+export interface ValidateResponse {
+  result: string;
+  valid: boolean;
+  output: string;
+}
+
+/** DOCX client options */
+export interface DocxClientOptions extends BaseClientOptions {
+  /** API URL. Defaults to Railway deployment */
+  apiUrl?: string;
+}
+
+/** DOCX agent options */
+export interface DocxAgentOptions extends BaseAgentOptions {
+  /** Current document ID */
+  documentId?: string;
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+/**
+ * @morphllm/subagents
+ *
+ * Modular AI subagents for document processing.
+ *
+ * Available subagents:
+ * - DOCX: Document editing with track changes and comments
+ * - PDF: Form filling (coming soon)
+ *
+ * @example
+ * ```typescript
+ * // Import specific subagent
+ * import { DocxClient, DocxAgent } from '@morphllm/subagents/docx';
+ *
+ * // Or import everything
+ * import { DocxClient, DocxAgent } from '@morphllm/subagents';
+ *
+ * // Use the client directly
+ * const client = new DocxClient();
+ * const doc = await client.upload(file);
+ * const content = await client.read(doc.doc_id);
+ *
+ * // Or use the AI agent
+ * const agent = new DocxAgent({
+ *   openai: new OpenAI({ apiKey: 'your-key' }),
+ *   documentId: doc.doc_id,
+ * });
+ * const result = await agent.run('Add a comment about the first paragraph');
+ * ```
+ */
+
+// Core exports
+export { BaseClient, BaseAgent } from './core';
+export type {
+  Tool,
+  ChatMessage,
+  ToolCall,
+  StreamEvent,
+  AgentRunResult,
+  BaseClientOptions,
+  BaseAgentOptions,
+} from './core';
+
+// DOCX exports
+export { DocxClient, DocxAgent } from './docx';
+export type {
+  DocumentInfo,
+  ReadResponse,
+  EditOperation,
+  EditOperationType,
+  EditResponse,
+  ValidateResponse,
+  DocxClientOptions,
+  DocxAgentOptions,
+} from './docx';
+
+// PDF exports (types only for now)
+export type {
+  PdfDocumentInfo,
+  FormField,
+  ReadFieldsResponse,
+  FillOperation,
+  FillResponse,
+  PdfClientOptions,
+  PdfAgentOptions,
+} from './pdf';

package/src/pdf/index.ts

@@ -0,0 +1,23 @@
+/**
+ * @morphllm/subagents/pdf
+ *
+ * PDF form filling subagent (coming soon).
+ *
+ * This module will provide:
+ * - PdfClient: HTTP client for PDF form API
+ * - PdfAgent: AI agent for filling PDF forms
+ */
+
+export type {
+  PdfDocumentInfo,
+  FormField,
+  ReadFieldsResponse,
+  FillOperation,
+  FillResponse,
+  PdfClientOptions,
+  PdfAgentOptions,
+} from './types';
+
+// Placeholder exports - will be implemented when PDF service is ready
+export const PdfClient = null;
+export const PdfAgent = null;

package/src/pdf/types.ts

@@ -0,0 +1,52 @@
+/**
+ * Types for PDF subagent (placeholder for future implementation)
+ */
+
+import type { BaseClientOptions, BaseAgentOptions } from '../core/types';
+
+/** PDF document info */
+export interface PdfDocumentInfo {
+  doc_id: string;
+  page_count: number;
+  message: string;
+}
+
+/** Form field information */
+export interface FormField {
+  name: string;
+  type: 'text' | 'checkbox' | 'radio' | 'dropdown' | 'signature';
+  value?: string;
+  options?: string[];
+  required?: boolean;
+  page: number;
+}
+
+/** Response from reading PDF form fields */
+export interface ReadFieldsResponse {
+  fields: FormField[];
+  page_count: number;
+}
+
+/** Fill operation for a form field */
+export interface FillOperation {
+  field_name: string;
+  value: string;
+}
+
+/** Response from fill operations */
+export interface FillResponse {
+  results: string[];
+  doc_id: string;
+}
+
+/** PDF client options */
+export interface PdfClientOptions extends BaseClientOptions {
+  /** API URL for PDF service */
+  apiUrl?: string;
+}
+
+/** PDF agent options */
+export interface PdfAgentOptions extends BaseAgentOptions {
+  /** Current document ID */
+  documentId?: string;
+}