io.Intelligence Working Context

Table of Contents

1. Introduction
2. Installation
3. Core Concepts
4. API Reference
5. Configuration
6. Integration Options
7. 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 collecting 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 Collection: 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:

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.

global: {
    names: string[]  // Array of global context names to track
}

2. Workspace Context

Context specific to workspaces (user's workspace or focused workspace).

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.

channel: {
  target: "my" | string; // "my" for user's channel or specific channel name
}

4. Application Instance Context

Context from specific application instances.

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:

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:

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:

get(): Record<string, Property>

Returns:

• Object containing all tracked properties with their current values

Property Structure:

interface Property {
  description?: string;
  value: any;
}

Example:

const currentContext = workingContext.get();
console.log(currentContext.userName.value); // "John Doe"

onChanged()

Subscribes to context changes.

Signature:

onChanged(
    callback: (data: Record<string, Property>) => void
): UnsubscribeFunction

Parameters:

• callback: Function called whenever context changes

Returns:

• Unsubscribe function to stop receiving updates

Example:

const unsubscribe = workingContext.onChanged((updatedContext) => {
  console.log("Context updated:", updatedContext);
});

// Later, to stop listening:
unsubscribe();

Configuration

Configuration Object Structure

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

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:

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/ai-web

Provides the best end-user experience with automatic context exposure to LLMs.

Use Case: Full-featured context-aware AI applications

Benefits:

• Automatic context collection
• 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

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

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

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",
        },
      },
    },
  },
};