@exellix/ai-tasks 8.4.1 → 8.4.3

package/.docs/building-runTask-sdk.md

@@ -0,0 +1,659 @@
+# Building a Minimal SDK with Only `runTask` Functionality
+
+This guide provides step-by-step instructions for creating a new SDK that uses `@woroces/ai-skills` and implements **only** the `runTask` functionality. This is useful when you want a lightweight wrapper that focuses exclusively on task execution without the full feature set of the main SDK.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Prerequisites](#prerequisites)
+3. [Project Setup](#project-setup)
+4. [Understanding `runTask`](#understanding-runtask)
+5. [Implementation Guide](#implementation-guide)
+6. [Complete Example](#complete-example)
+7. [Testing](#testing)
+8. [Advanced Configuration](#advanced-configuration)
+9. [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+The `runTask` method is a specialized execution method that:
+- Executes tasks with a specific execution strategy (currently only `DIRECT`)
+- Enriches memories with scoping data (if Context Manager is available)
+- Generates context markdown from enriched memories
+- Delegates to the underlying skill executor
+- Returns structured FlexMD responses
+
+**Key Difference from `runSkill`**: `runTask` includes additional context enrichment steps and supports execution types, making it suitable for more complex orchestration scenarios.
+
+---
+
+## Prerequisites
+
+Before starting, ensure you have:
+
+- **Node.js** >= 18.0.0
+- **npm** or **yarn** package manager
+- **TypeScript** knowledge
+- Access to GitHub Package Registry (for installing `@woroces/ai-skills`)
+- A GitHub token with package read permissions (if using remote content registry)
+
+---
+
+## Project Setup
+
+### Step 1: Initialize Your Project
+
+```bash
+mkdir my-task-sdk
+cd my-task-sdk
+npm init -y
+```
+
+### Step 2: Install TypeScript and Build Tools
+
+```bash
+npm install --save-dev typescript @types/node ts-node
+```
+
+### Step 3: Configure TypeScript
+
+Create `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
+```
+
+### Step 4: Configure npm Registry for GitHub Packages
+
+Create `.npmrc` file:
+
+```
+@woroces:registry=https://npm.pkg.github.com
+@athenices:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN_HERE
+```
+
+Replace `YOUR_GITHUB_TOKEN_HERE` with your GitHub personal access token that has `read:packages` permission.
+
+### Step 5: Install Core Dependencies
+
+```bash
+npm install @woroces/ai-skills @athenices/ai-gateway
+```
+
+**Note**: The `@woroces/ai-skills` package will automatically pull in its dependencies:
+- `@athenices/ai-gateway` (already listed)
+- `@athenices/execution-memory-manager`
+- `@athenices/xontext` (optional, for context enrichment)
+- `logs-gateway`
+- `nx-config2`
+- `nx-helpers`
+
+### Step 6: Update package.json Scripts
+
+Add build and development scripts:
+
+```json
+{
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "prepublishOnly": "npm run build"
+  }
+}
+```
+
+---
+
+## Understanding `runTask`
+
+### API Signature
+
+```typescript
+async runTask<TParsed = any>(
+  input: RunTaskRequest
+): Promise<RunSkillResponse<TParsed>>
+```
+
+### Input Interface: `RunTaskRequest`
+
+```typescript
+interface RunTaskRequest {
+  skillKey: string;                    // "skills/professional-answer" or "tasks/..."
+  input: Record<string, any> | string; // Task input data
+  executionType: ExecutionType;        // Currently only ExecutionType.DIRECT
+  
+  // Optional fields
+  variables?: Record<string, any>;      // Contextual variables (e.g., orgName, tone)
+  context?: Record<string, any> | string; // Additional context
+  knowledge?: Record<string, any>;     // Knowledge base data
+  
+  // Memory management
+  jobMemory?: JobHistory;               // History of all previous task results
+  taskMemory?: TaskHistory;             // History of skills executed up to this task
+  
+  // Identifiers
+  jobId?: string;
+  agentId?: string;
+  skillId?: string;
+  masterSkillId?: string;
+  masterSkillActivityId?: string;
+  
+  // Configuration
+  timeoutMs?: number;                   // Request timeout in milliseconds
+}
+```
+
+### Output Interface: `RunSkillResponse<TParsed>`
+
+```typescript
+interface RunSkillResponse<TParsed = any> {
+  skillKey: string;                    // The skill key that was executed
+  rawText: string;                     // Raw response from the gateway
+  flexMd: {
+    frame: string;                     // FlexMD frame name (e.g., "professional-answer")
+    payloads: Record<string, string>;  // Parsed payloads from FlexMD
+  };
+  parsed: TParsed;                     // Typed parsed data (same as payloads by default)
+  metadata: {
+    instructionVersion?: string;        // Version of the instruction used
+    activityId?: string;                // Unique activity identifier
+  };
+}
+```
+
+### ExecutionType Enum
+
+```typescript
+enum ExecutionType {
+  DIRECT = "direct"  // Currently the only supported type
+}
+```
+
+### How `runTask` Works Internally
+
+1. **Extract Task ID**: Removes `"tasks/"` prefix from `skillKey` if present
+2. **Build Memory Bundle**: Combines `jobMemory` and `taskMemory`
+3. **Enrich Memories** (if Context Manager available):
+   - Retrieves scoping definitions for the task
+   - Executes scoping queries
+   - Integrates results into memory bundle
+4. **Generate Context Markdown** (if Context Manager available):
+   - Uses context maps to generate markdown from enriched memories
+5. **Execute Task**: Delegates to `TaskExecutor` which:
+   - For `DIRECT` type: Passes through to `SkillExecutor`
+   - `SkillExecutor` invokes the AI Gateway
+   - Parses FlexMD response
+   - Returns structured result
+
+---
+
+## Implementation Guide
+
+### Step 1: Create the Main SDK Class
+
+Create `src/task-sdk.ts`:
+
+```typescript
+import { 
+  XeonoxSkillsClient, 
+  RunTaskRequest, 
+  RunSkillResponse, 
+  ExecutionType 
+} from "@woroces/ai-skills";
+import type { XeonoxSkillsClientOptions } from "@woroces/ai-skills";
+
+/**
+ * Minimal Task SDK
+ * 
+ * A lightweight wrapper around @woroces/ai-skills that provides
+ * only the runTask functionality.
+ */
+export class TaskSDK {
+  private client: XeonoxSkillsClient;
+
+  constructor(options?: XeonoxSkillsClientOptions) {
+    // Initialize the underlying client
+    // The client handles all the complexity: gateway setup, registry management, etc.
+    this.client = new XeonoxSkillsClient(options);
+  }
+
+  /**
+   * Execute a task with the specified execution type.
+   * 
+   * @param request The task execution request
+   * @returns Promise resolving to the task response
+   */
+  async runTask<TParsed = any>(
+    request: RunTaskRequest
+  ): Promise<RunSkillResponse<TParsed>> {
+    // Ensure executionType is set (default to DIRECT if not provided)
+    const taskRequest: RunTaskRequest = {
+      ...request,
+      executionType: request.executionType || ExecutionType.DIRECT
+    };
+
+    // Delegate to the underlying client
+    return this.client.runTask<TParsed>(taskRequest);
+  }
+
+  /**
+   * Convenience method for direct task execution.
+   * 
+   * @param skillKey The skill key to execute
+   * @param input The input data
+   * @param options Optional additional parameters
+   */
+  async executeDirect<TParsed = any>(
+    skillKey: string,
+    input: Record<string, any> | string,
+    options?: {
+      variables?: Record<string, any>;
+      context?: Record<string, any> | string;
+      knowledge?: Record<string, any>;
+      jobMemory?: any;
+      taskMemory?: any;
+      jobId?: string;
+      agentId?: string;
+      timeoutMs?: number;
+    }
+  ): Promise<RunSkillResponse<TParsed>> {
+    return this.runTask<TParsed>({
+      skillKey,
+      input,
+      executionType: ExecutionType.DIRECT,
+      ...options
+    });
+  }
+}
+
+// Re-export types for convenience
+export type { RunTaskRequest, RunSkillResponse } from "@woroces/ai-skills";
+export { ExecutionType } from "@woroces/ai-skills";
+```
+
+### Step 2: Create the Main Entry Point
+
+Create `src/index.ts`:
+
+```typescript
+export { TaskSDK } from "./task-sdk";
+export type { RunTaskRequest, RunSkillResponse } from "@woroces/ai-skills";
+export { ExecutionType } from "@woroces/ai-skills";
+```
+
+### Step 3: Update package.json
+
+Add proper metadata:
+
+```json
+{
+  "name": "my-task-sdk",
+  "version": "1.0.0",
+  "description": "Minimal SDK for task execution using @woroces/ai-skills",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "keywords": ["ai", "tasks", "llm", "skills"],
+  "author": "Your Name",
+  "license": "ISC"
+}
+```
+
+---
+
+## Complete Example
+
+### Example 1: Basic Usage
+
+Create `examples/basic-usage.ts`:
+
+```typescript
+import { TaskSDK, ExecutionType } from "../src";
+import * as dotenv from "dotenv";
+
+dotenv.config();
+
+async function basicExample() {
+  // Initialize the SDK
+  const sdk = new TaskSDK({
+    packageName: "MY-TASK-SDK",
+    enableContentRegistry: true,
+    contentRegistryLocalPath: "./.metadata" // or use remote registry
+  });
+
+  // Execute a task
+  const result = await sdk.runTask({
+    skillKey: "skills/professional-answer",
+    executionType: ExecutionType.DIRECT,
+    input: {
+      question: "What is the capital of France?"
+    },
+    variables: {
+      orgName: "MyOrganization",
+      tone: "professional"
+    }
+  });
+
+  console.log("Task executed successfully!");
+  console.log("Frame:", result.flexMd.frame);
+  console.log("Payloads:", result.flexMd.payloads);
+  console.log("Parsed:", result.parsed);
+}
+
+basicExample().catch(console.error);
+```
+
+### Example 2: Using Convenience Method
+
+```typescript
+import { TaskSDK } from "../src";
+
+async function convenienceExample() {
+  const sdk = new TaskSDK({
+    enableContentRegistry: true
+  });
+
+  const result = await sdk.executeDirect(
+    "skills/professional-answer",
+    { question: "Explain quantum computing" },
+    {
+      variables: { orgName: "TechCorp" },
+      jobId: "job-123",
+      agentId: "agent-abc"
+    }
+  );
+
+  // Access the structured response
+  const shortAnswer = result.flexMd.payloads.shortAnswer;
+  const fullAnswer = result.flexMd.payloads.fullAnswer;
+  
+  console.log("Short Answer:", shortAnswer);
+  console.log("Full Answer:", fullAnswer);
+}
+
+convenienceExample().catch(console.error);
+```
+
+### Example 3: With Memory Management
+
+```typescript
+import { TaskSDK, ExecutionType } from "../src";
+import type { JobHistory, TaskHistory } from "@athenices/execution-memory-manager";
+
+async function withMemoryExample() {
+  const sdk = new TaskSDK();
+
+  // Build up memory from previous tasks
+  const jobMemory: JobHistory = {
+    // Previous task results
+  };
+
+  const taskMemory: TaskHistory = {
+    // Previous skill executions
+  };
+
+  const result = await sdk.runTask({
+    skillKey: "skills/professional-decision",
+    executionType: ExecutionType.DIRECT,
+    input: {
+      scenario: "Should we migrate to cloud?"
+    },
+    variables: {
+      orgName: "EnterpriseCorp"
+    },
+    jobMemory,
+    taskMemory,
+    jobId: "job-456"
+  });
+
+  console.log("Decision:", result.parsed);
+}
+
+withMemoryExample().catch(console.error);
+```
+
+---
+
+## Testing
+
+### Step 1: Create Test File
+
+Create `src/task-sdk.test.ts`:
+
+```typescript
+import { TaskSDK, ExecutionType } from "./task-sdk";
+import * as dotenv from "dotenv";
+
+dotenv.config();
+
+describe("TaskSDK", () => {
+  let sdk: TaskSDK;
+
+  beforeAll(() => {
+    sdk = new TaskSDK({
+      packageName: "TEST-SDK",
+      enableContentRegistry: true,
+      contentRegistryLocalPath: "./.metadata"
+    });
+  });
+
+  test("should execute a direct task", async () => {
+    const result = await sdk.runTask({
+      skillKey: "skills/professional-answer",
+      executionType: ExecutionType.DIRECT,
+      input: {
+        question: "What is 2+2?"
+      },
+      variables: {
+        orgName: "TestOrg"
+      }
+    });
+
+    expect(result).toBeDefined();
+    expect(result.skillKey).toBe("skills/professional-answer");
+    expect(result.flexMd).toBeDefined();
+    expect(result.flexMd.frame).toBeDefined();
+    expect(result.flexMd.payloads).toBeDefined();
+  });
+
+  test("should use convenience method", async () => {
+    const result = await sdk.executeDirect(
+      "skills/professional-answer",
+      { question: "Test question" }
+    );
+
+    expect(result).toBeDefined();
+    expect(result.skillKey).toBe("skills/professional-answer");
+  });
+});
+```
+
+### Step 2: Install Testing Dependencies
+
+```bash
+npm install --save-dev jest @types/jest ts-jest
+```
+
+### Step 3: Configure Jest
+
+Create `jest.config.js`:
+
+```javascript
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/*.test.ts'],
+  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.test.ts']
+};
+```
+
+---
+
+## Advanced Configuration
+
+### Environment Variables
+
+The SDK uses environment variables for automatic configuration (ERC mode):
+
+```bash
+# Required for GitHub-based content registry
+export GITHUB_TOKEN=your_github_token
+export GITHUB_REPO_URL=https://github.com/your-org/content-registry
+
+# AI Provider Keys (at least one required)
+export OPENAI_API_KEY=your_openai_key
+# OR
+export GROK_API_KEY=your_grok_key
+
+# Optional: MongoDB for context enrichment
+export MONGODB_URI=mongodb://localhost:27017/your-db
+```
+
+### Custom Gateway Configuration
+
+You can provide a pre-configured gateway:
+
+```typescript
+import { AIGateway } from "@athenices/ai-gateway";
+import { TaskSDK } from "./src";
+
+// Create custom gateway
+const gateway = new AIGateway({
+  packageName: "CUSTOM-GATEWAY",
+  enableActivityTracking: true,
+  enableContentRegistry: true,
+  // ... other gateway options
+});
+
+// Use it in the SDK
+const sdk = new TaskSDK({
+  gateway: gateway
+});
+```
+
+### Local Development Mode
+
+For offline development:
+
+```typescript
+const sdk = new TaskSDK({
+  enableContentRegistry: true,
+  contentRegistryLocalPath: "./local-metadata",
+  forceLocal: true, // Bypass remote registry
+  forceCreateRootDirectory: true // Auto-create directories
+});
+```
+
+---
+
+## Troubleshooting
+
+### Issue: "Content not found" Error
+
+**Problem**: The skill key cannot be resolved.
+
+**Solutions**:
+1. Verify the skill key format: `"skills/professional-answer"` (not `"professional-answer"`)
+2. Ensure content registry contains the skill at the expected path
+3. Check `contentRegistryLocalPath` if using local registry
+4. Verify `GITHUB_TOKEN` and `GITHUB_REPO_URL` if using remote registry
+
+### Issue: "Repository not accessible"
+
+**Problem**: Cannot connect to GitHub content registry.
+
+**Solutions**:
+1. Verify `GITHUB_TOKEN` has correct permissions (`repo` scope for private repos)
+2. Check `GITHUB_REPO_URL` points to an existing repository
+3. Ensure repository is accessible (not private without proper token)
+
+### Issue: "Unsupported execution type"
+
+**Problem**: Using an execution type other than `DIRECT`.
+
+**Solution**: Currently only `ExecutionType.DIRECT` is supported. Ensure you're using:
+```typescript
+executionType: ExecutionType.DIRECT
+```
+
+### Issue: "Environment validation failed"
+
+**Problem**: Missing required environment variables.
+
+**Solutions**:
+1. Ensure at least one AI provider key is set (`OPENAI_API_KEY` or `GROK_API_KEY`)
+2. If using remote registry, set `GITHUB_TOKEN` and `GITHUB_REPO_URL`
+3. Check `.env` file is loaded (if using `dotenv`)
+
+### Issue: TypeScript compilation errors
+
+**Problem**: Type definitions not found.
+
+**Solutions**:
+1. Ensure `@woroces/ai-skills` is installed: `npm install @woroces/ai-skills`
+2. Check `tsconfig.json` includes proper module resolution
+3. Verify `skipLibCheck: true` in `tsconfig.json` if needed
+
+---
+
+## Summary
+
+You've now created a minimal SDK that:
+
+1. ✅ Wraps `@woroces/ai-skills` with a focused API
+2. ✅ Provides only `runTask` functionality
+3. ✅ Includes convenience methods for common use cases
+4. ✅ Handles all underlying complexity (gateway, registry, parsing)
+5. ✅ Supports both local and remote content registries
+6. ✅ Includes proper TypeScript types
+
+### Key Takeaways
+
+- **Minimal Surface Area**: Your SDK only exposes `runTask`, keeping the API simple
+- **Full Power Underneath**: You still get all the benefits of the full SDK (context enrichment, memory management, FlexMD parsing)
+- **Easy to Extend**: You can add more methods later if needed
+- **Type Safe**: Full TypeScript support with proper type inference
+
+### Next Steps
+
+1. Add error handling wrappers
+2. Implement retry logic
+3. Add request/response logging
+4. Create additional convenience methods
+5. Add validation for inputs
+6. Implement caching if needed
+
+---
+
+## Additional Resources
+
+- [@woroces/ai-skills README](../README.md) - Full SDK documentation
+- [FlexMD Format Documentation](../docs/metadata.md) - Understanding FlexMD responses
+- [Content Registry Guide](../README.md#content-registry) - Setting up content registry
+- [AI Gateway Documentation](https://github.com/athenices/ai-gateway) - Understanding the underlying gateway
+
+---
+
+**Questions?** Check the main SDK documentation or open an issue in the repository.