@interopio/working-context 0.1.1-beta.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@interopio/working-context",
+  "version": "0.1.1-beta.0",
+  "type": "module",
+  "description": "io.Intelligence Working Context for LLMs",
+  "main": "./dist/working-context.umd.js",
+  "module": "./dist/working-context.es.js",
+  "types": "./working-context.d.ts",
+  "exports": {
+    ".": {
+      "types": "./working-context.d.ts",
+      "import": "./dist/working-context.es.js",
+      "require": "./dist/working-context.umd.js"
+    }
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "build:docker": "rollup -c",
+    "test": "karma start karma.conf.cjs --single-run",
+    "version": "npm run build"
+  },
+  "dependencies": {
+    "@interopio/browser": "^4.0.0",
+    "@interopio/desktop": "^6.0.0"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "agentic",
+    "copilot",
+    "assistant",
+    "io.Intelligence",
+    "io.connect",
+    "interop.io",
+    "io.connect browser",
+    "io.connect desktop",
+    "io.connect browser platform"
+  ],
+  "homepage": "https://interop.io/",
+  "author": {
+    "name": "Interop.IO",
+    "url": "https://interop.io/"
+  },
+  "publishConfig": {
+    "@interopio:registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "license": "MIT",
+  "gitHead": "6cbd953e1718cca987f11c0bc7edb75781f7ecb2"
+}

package/readme.md

@@ -0,0 +1,530 @@
+# io.Intelligence Working Context
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Installation](#installation)
+3. [Core Concepts](#core-concepts)
+4. [API Reference](#api-reference)
+5. [Configuration](#configuration)
+6. [Integration Options](#integration-options)
+7. [Examples](#examples)
+
+---
+
+## Introduction
+
+The **io.Intelligence Working Context** package (`@interopio/working-context`) is a TypeScript library that enables developers to build intelligent, context-aware applications by automatically harvesting and managing contextual information gathered from multiple data sources within io.Connect.
+
+### What is Working Context?
+
+Working Context represents the current state and information relevant to a user's workflow. This package automatically tracks, updates, and exposes contextual data from various sources within your application, making it readily available for AI agents, LLMs, or application logic.
+
+### Key Features
+
+- **Automatic Context Harvesting**: Define schemas describing your data sources, and the package handles the rest
+- **Multiple Source Support**: Track data from global contexts, workspaces, channels, and application instances
+- **Type-Safe**: Built with TypeScript for complete type safety and IntelliSense support
+- **Reactive Updates**: Subscribe to context changes and respond to updates in real-time
+- **Flexible Integration**: Works standalone or integrates with other io.Intelligence packages
+
+## Installation
+
+The package is available via npm and can be installed using npm or yarn:
+
+```bash
+npm install @interopio/working-context
+```
+
+## Core Concepts
+
+### Schema-Driven Configuration
+
+The Working Context package operates on a schema-like configuration object that defines:
+
+1. **Properties to track**: Each property has a name and expected data type
+2. **Source locations**: Where to find the data (global context, workspace, channel, etc.)
+3. **Data paths**: The specific path within each source to extract values
+
+### Context Sources
+
+The package supports four types of context sources:
+
+#### 1. Global Context
+
+Global io.Connect shared contexts accessible across the entire io.Connect environment.
+
+```typescript
+global: {
+    names: string[]  // Array of global context names to track
+}
+```
+
+#### 2. Workspace Context
+
+Context specific to workspaces (user's workspace or focused workspace).
+
+```typescript
+workspace: {
+  target: "my" | "focused" | "hybrid";
+}
+```
+
+> **Note**: "focused" and "hybrid" targets are currently supported only in io.Connect Desktop.
+
+#### 3. Channel Context
+
+Data from specific channels.
+
+```typescript
+channel: {
+  target: "my" | string; // "my" for user's channel or specific channel name
+}
+```
+
+#### 4. Application Instance Context
+
+Context from specific application instances.
+
+```typescript
+appInstance: {
+    appNames: string[]  // Array of application names to track
+}
+```
+
+### Property Types
+
+The package supports five data types for tracked properties:
+
+- `string`: Text values
+- `number`: Numeric values
+- `boolean`: True/false values
+- `object`: Complex objects (non-array)
+- `array`: Array values
+
+---
+
+## API Reference
+
+### Factory Function
+
+#### `IoIntelWorkingContextFactory`
+
+The main entry point for creating a Working Context instance.
+
+**Signature:**
+
+```typescript
+IoIntelWorkingContextFactory(
+    io: IOConnectBrowser.API,
+    config: IoIntelWorkingContext.Config
+): Promise<IoIntelWorkingContext.API>
+```
+
+**Parameters:**
+
+- `io`: The io.Connect browser API instance. **Note:** Providing an io.Connect API with Workspaces API configured is required for all Workspaces tracking.
+- `config`: Configuration object defining the schema and sources
+
+**Returns:**
+
+- A Promise that resolves to the Working Context API
+
+**Example:**
+
+```typescript
+import { IoIntelWorkingContextFactory } from "@interopio/working-context";
+
+const workingContext = await IoIntelWorkingContextFactory(io, {
+  schema: {
+    userName: {
+      type: "string",
+      description: "Current user's full name",
+      source: {
+        context: {
+          location: {
+            global: { names: ["UserProfile"] },
+          },
+          path: "user.name",
+        },
+      },
+    },
+  },
+});
+```
+
+### Working Context API
+
+Once initialized, the Working Context API provides two main methods:
+
+#### `get()`
+
+Retrieves the current state of all tracked properties.
+
+**Signature:**
+
+```typescript
+get(): Record<string, Property>
+```
+
+**Returns:**
+
+- Object containing all tracked properties with their current values
+
+**Property Structure:**
+
+```typescript
+interface Property {
+  description?: string;
+  value: any;
+}
+```
+
+**Example:**
+
+```typescript
+const currentContext = workingContext.get();
+console.log(currentContext.userName.value); // "John Doe"
+```
+
+#### `onChanged()`
+
+Subscribes to context changes.
+
+**Signature:**
+
+```typescript
+onChanged(
+    callback: (data: Record<string, Property>) => void
+): UnsubscribeFunction
+```
+
+**Parameters:**
+
+- `callback`: Function called whenever context changes
+
+**Returns:**
+
+- Unsubscribe function to stop receiving updates
+
+**Example:**
+
+```typescript
+const unsubscribe = workingContext.onChanged((updatedContext) => {
+  console.log("Context updated:", updatedContext);
+});
+
+// Later, to stop listening:
+unsubscribe();
+```
+
+---
+
+## Configuration
+
+### Configuration Object Structure
+
+```typescript
+interface Config {
+  schema: Schema;
+}
+
+interface Schema {
+  [key: string]: PropertySchema;
+}
+
+interface PropertySchema {
+  type: "string" | "number" | "boolean" | "object" | "array";
+  description?: string;
+  source: Source;
+}
+
+interface Source {
+  context: {
+    location: SourceLocation;
+    path: string; // Dot notation path
+  };
+}
+
+interface SourceLocation {
+  global?: { names: string[] };
+  workspace?: { target: "my" | "focused" | "hybrid" };
+  appInstance?: { appNames: string[] };
+  channel?: { target: "my" | string };
+}
+```
+
+### Configuration Rules
+
+1. **Single Source Location**: Each property must define exactly one source location (global, workspace, appInstance, or channel)
+2. **Dot Notation Paths**: Use dot notation for nested paths (e.g., `"user.profile.email"`)
+3. **Type Validation**: Values are validated against declared types; mismatches are logged and ignored
+
+### Complete Configuration Example
+
+```typescript
+const config = {
+  schema: {
+    // Track user name from global context
+    userName: {
+      type: "string",
+      description: "User's display name",
+      source: {
+        context: {
+          location: {
+            global: { names: ["UserSession", "UserProfile"] },
+          },
+          path: "name",
+        },
+      },
+    },
+
+    // Track active document from workspace
+    activeDocument: {
+      type: "object",
+      description: "Currently open document",
+      source: {
+        context: {
+          location: {
+            workspace: { target: "my" },
+          },
+          path: "document.current",
+        },
+      },
+    },
+
+    // Track notification settings from channel
+    notificationsEnabled: {
+      type: "boolean",
+      source: {
+        context: {
+          location: {
+            channel: { target: "my" },
+          },
+          path: "settings.notifications.enabled",
+        },
+      },
+    },
+
+    // Track portfolio data from specific app instance
+    portfolioData: {
+      type: "array",
+      description: "User's portfolio holdings",
+      source: {
+        context: {
+          location: {
+            appInstance: { appNames: ["PortfolioManager"] },
+          },
+          path: "portfolio.holdings",
+        },
+      },
+    },
+  },
+};
+```
+
+---
+
+## Integration Options
+
+The Working Context package offers three integration approaches:
+
+### 1. Standalone Usage
+
+Use the package directly via its API for custom implementations.
+
+**Use Case**: Custom solutions requiring direct control over context management
+
+**Example:**
+
+```typescript
+import { IoIntelWorkingContextFactory } from "@interopio/working-context";
+import IOConnectBrowser from "@interopio/browser";
+
+async function initializeContext() {
+  const io = await IOConnectBrowser();
+
+  const workingContext = await IoIntelWorkingContextFactory(io, config);
+
+  // Get current context
+  const context = workingContext.get();
+
+  // Subscribe to changes
+  workingContext.onChanged((data) => {
+    // Handle context updates
+    processContextUpdate(data);
+  });
+}
+```
+
+### 2. Integration with `@interopio/intel-web`
+
+Provides the best end-user experience with automatic context exposure to LLMs.
+
+**Use Case**: Full-featured context-aware AI applications
+
+**Benefits:**
+
+- Automatic context harvesting
+- Fine-tuned prompts for LLM integration
+- Seamless API access if no LLM is configured
+
+### 3. Integration with `@interopio/mcp-core`
+
+Designed for solutions using only the io.Intelligence MCP (Model Context Protocol).
+
+**Use Case**: MCP-only solutions without other io.Intelligence packages
+
+**Implementation:**
+
+- Context exposed via dedicated MCP tool
+- Requires custom prompt engineering
+- Developer manages LLM system prompts
+
+## Examples
+
+### Example 1: Tracking User Profile
+
+```typescript
+import { IoIntelWorkingContextFactory } from "@interopio/working-context";
+
+const config = {
+  schema: {
+    userId: {
+      type: "string",
+      description: "Unique user identifier",
+      source: {
+        context: {
+          location: { global: { names: ["UserSession"] } },
+          path: "user.id",
+        },
+      },
+    },
+    userName: {
+      type: "string",
+      description: "User's full name",
+      source: {
+        context: {
+          location: { global: { names: ["UserSession"] } },
+          path: "user.fullName",
+        },
+      },
+    },
+    userRole: {
+      type: "string",
+      description: "User's role in the organization",
+      source: {
+        context: {
+          location: { global: { names: ["UserSession"] } },
+          path: "user.role",
+        },
+      },
+    },
+  },
+};
+
+const workingContext = await IoIntelWorkingContextFactory(io, config);
+
+// Access user information
+const context = workingContext.get();
+console.log(`Welcome, ${context.userName.value}!`);
+console.log(`Role: ${context.userRole.value}`);
+```
+
+### Example 2: Multi-Source Trading Application
+
+```typescript
+const tradingConfig = {
+  schema: {
+    // From global context
+    traderId: {
+      type: "string",
+      source: {
+        context: {
+          location: { global: { names: ["TraderProfile"] } },
+          path: "trader.id",
+        },
+      },
+    },
+
+    // From workspace
+    activeInstrument: {
+      type: "object",
+      description: "Currently selected trading instrument",
+      source: {
+        context: {
+          location: { workspace: { target: "my" } },
+          path: "instrument",
+        },
+      },
+    },
+
+    // From channel
+    marketData: {
+      type: "object",
+      description: "Real-time market data",
+      source: {
+        context: {
+          location: { channel: { target: "MarketData" } },
+          path: "data",
+        },
+      },
+    },
+
+    // From app instance
+    openOrders: {
+      type: "array",
+      description: "List of open orders",
+      source: {
+        context: {
+          location: { appInstance: { appNames: ["OrderManager"] } },
+          path: "orders.open",
+        },
+      },
+    },
+  },
+};
+
+const tradingContext = await IoIntelWorkingContextFactory(io, tradingConfig);
+
+// Monitor trading context
+tradingContext.onChanged((context) => {
+  if (context.activeInstrument.value) {
+    console.log(
+      `Instrument changed to: ${context.activeInstrument.value.symbol}`,
+    );
+  }
+
+  if (context.openOrders.value) {
+    console.log(`Open orders: ${context.openOrders.value.length}`);
+  }
+});
+```
+
+### Example 3: Deeply Nested Data Paths
+
+```typescript
+const nestedConfig = {
+  schema: {
+    departmentName: {
+      type: "string",
+      source: {
+        context: {
+          location: { global: { names: ["OrgStructure"] } },
+          path: "organization.division.department.name",
+        },
+      },
+    },
+
+    budgetRemaining: {
+      type: "number",
+      source: {
+        context: {
+          location: { global: { names: ["FinanceData"] } },
+          path: "department.finance.budget.fiscal2024.remaining",
+        },
+      },
+    },
+  },
+};
+```