@exellix/ai-tasks 9.0.6 → 9.1.1

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

@@ -1,659 +0,0 @@
-# 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.