@nxuss/lemma 0.3.3 → 0.4.1

package/src/protocol/README.md

@@ -0,0 +1,576 @@
+# Inter-Agent Protocol (I.A.P.) v1.0.0
+
+## Overview
+
+The **Inter-Agent Protocol (I.A.P.)** is a lightweight, WebSocket-based communication standard that enables autonomous AI agents to discover, negotiate, and collaborate seamlessly across different frameworks and platforms.
+
+I.A.P. solves the fragmentation problem in multi-agent systems by providing a common language for:
+- **Agent identification and capability broadcasting**
+- **Dynamic task negotiation and bidding**
+- **Stateful context transfer between agents**
+- **Real-time performance monitoring**
+
+## Core Concepts
+
+### 1. Agent Identity
+
+Every agent in the network has a unique `AgentId` and advertises its capabilities through a structured handshake process.
+
+```typescript
+interface AgentHandshake {
+  agentId: string;
+  name: string;
+  version: string;
+  framework?: string;
+  capabilities: AgentCapability[];
+  maxConcurrentTasks?: number;
+  currentLoad?: number;
+  protocolVersion: string;
+}
+```
+
+### 2. Capabilities
+
+Capabilities define what an agent can do. Each capability includes:
+- **Type**: Predefined category (text generation, code execution, etc.)
+- **Input/Output schemas**: JSON Schema definitions
+- **Performance metrics**: Estimated cost and latency
+
+```typescript
+interface AgentCapability {
+  id: string;
+  type: CapabilityType;
+  name: string;
+  description: string;
+  inputSchema?: Record<string, any>;
+  outputSchema?: Record<string, any>;
+  estimatedCost?: number;
+  averageLatency?: number;
+}
+```
+
+### 3. Task Negotiation
+
+Tasks flow through a bidding process:
+1. **Proposal**: An agent proposes a task with requirements
+2. **Bidding**: Capable agents submit bids with cost/latency estimates
+3. **Assignment**: Router selects the optimal agent
+4. **Execution**: Assigned agent executes and returns results
+
+### 4. Context Transfer
+
+Agents can pass stateful information without re-summarizing:
+
+```typescript
+interface ContextTransfer {
+  fromAgent: AgentId;
+  toAgent: AgentId;
+  taskId: TaskId;
+  contextType: string;
+  data: Record<string, any>;
+  embedding?: number[];  // For semantic indexing
+  compression?: 'gzip' | 'brotli' | 'none';
+}
+```
+
+## Protocol Flows
+
+### Connection Flow
+
+```mermaid
+sequenceDiagram
+    participant Agent
+    participant Router
+    
+    Agent->>Router: HANDSHAKE (capabilities)
+    Router->>Agent: HANDSHAKE_ACK (session)
+    loop Maintain Connection
+        Agent->>Router: HEARTBEAT
+    end
+    Agent->>Router: DISCONNECT
+```
+
+**Steps:**
+1. Agent sends `HANDSHAKE` with capabilities
+2. Router responds with `HANDSHAKE_ACK` and session ID
+3. Agent sends periodic `HEARTBEAT` messages
+4. Agent sends `DISCONNECT` when leaving
+
+### Discovery Flow
+
+```mermaid
+sequenceDiagram
+    participant Agent A
+    participant Router
+    
+    Agent A->>Router: CAPABILITY_DISCOVERY
+    Router->>Agent A: CAPABILITY_RESPONSE (all agents)
+```
+
+**Steps:**
+1. Agent sends `CAPABILITY_DISCOVERY` request
+2. Router responds with all available agents and their capabilities
+
+### Task Negotiation Flow
+
+```mermaid
+sequenceDiagram
+    participant Agent A
+    participant Router
+    participant Agent B
+    participant Agent C
+    
+    Agent A->>Router: TASK_PROPOSAL
+    Router->>Agent B: TASK_PROPOSAL (broadcast)
+    Router->>Agent C: TASK_PROPOSAL (broadcast)
+    Agent B->>Router: TASK_BID
+    Agent C->>Router: TASK_BID
+    Router->>Agent B: TASK_ASSIGNMENT (best bid)
+    Agent B->>Router: TASK_ACCEPTANCE
+    Agent B->>Router: TASK_RESULT
+    Router->>Agent A: TASK_RESULT
+```
+
+**Steps:**
+1. Agent A proposes a task to the router
+2. Router broadcasts to all capable agents
+3. Agents B and C submit bids
+4. Router assigns to best bidder (Agent B)
+5. Agent B accepts and executes
+6. Agent B returns result to router
+7. Router forwards result to Agent A
+
+### Context Transfer Flow
+
+```mermaid
+sequenceDiagram
+    participant Agent A
+    participant Router
+    participant Agent B
+    
+    Agent A->>Router: CONTEXT_TRANSFER
+    Router->>Agent B: CONTEXT_TRANSFER
+```
+
+**Steps:**
+1. Agent A sends context to router
+2. Router forwards to Agent B
+3. Agent B continues execution with transferred state
+
+## Message Types
+
+### Core Messages
+
+| Type | Direction | Purpose |
+|------|-----------|---------|
+| `HANDSHAKE` | Agent → Router | Initial connection and capability registration |
+| `HANDSHAKE_ACK` | Router → Agent | Connection acknowledgment |
+| `CAPABILITY_DISCOVERY` | Agent → Router | Query available capabilities |
+| `CAPABILITY_RESPONSE` | Router → Agent | List of agents and capabilities |
+| `TASK_PROPOSAL` | Agent → Router | Propose a task for execution |
+| `TASK_BID` | Agent → Router | Bid on a proposed task |
+| `TASK_ASSIGNMENT` | Router → Agent | Assign task to winning bidder |
+| `TASK_ACCEPTANCE` | Agent → Router | Accept assigned task |
+| `TASK_REJECTION` | Agent → Router | Reject assigned task |
+| `CONTEXT_TRANSFER` | Agent ↔ Agent | Transfer execution context |
+| `TASK_RESULT` | Agent → Router | Return task execution result |
+| `ERROR` | Any → Any | Error notification |
+| `HEARTBEAT` | Agent → Router | Keep-alive signal |
+| `DISCONNECT` | Agent → Router | Graceful disconnect |
+
+## Message Structure
+
+All I.A.P. messages follow a common structure:
+
+```typescript
+interface IAPMessage {
+  messageId: string;           // Unique message identifier
+  type: MessageType;           // Message type
+  from: AgentId;               // Sender
+  to: AgentId | 'router';      // Recipient
+  timestamp: string;           // ISO 8601 timestamp
+  protocolVersion: string;     // Protocol version (1.0.0)
+  payload: any;                // Type-specific payload
+  correlationId?: string;      // For request-response tracking
+  metadata?: Record<string, any>;
+}
+```
+
+## Usage Examples
+
+### 1. Agent Registration
+
+```typescript
+import { 
+  createHandshakeMessage, 
+  AgentHandshake, 
+  CapabilityType 
+} from './protocol';
+
+const handshake: AgentHandshake = {
+  agentId: 'agent_langchain_001',
+  name: 'LangChain Code Assistant',
+  version: '1.0.0',
+  framework: 'LangChain',
+  protocolVersion: '1.0.0',
+  capabilities: [
+    {
+      id: 'code_gen_python',
+      type: CapabilityType.CODE_EXECUTION,
+      name: 'Python Code Generation',
+      description: 'Generate and execute Python code',
+      estimatedCost: 100,
+      averageLatency: 2000
+    }
+  ],
+  maxConcurrentTasks: 5,
+  currentLoad: 0.2
+};
+
+const message = createHandshakeMessage(handshake);
+websocket.send(JSON.stringify(message));
+```
+
+### 2. Task Proposal
+
+```typescript
+import { 
+  createTaskProposalMessage, 
+  TaskProposal, 
+  CapabilityType,
+  generateTaskId 
+} from './protocol';
+
+const proposal: TaskProposal = {
+  taskId: generateTaskId(),
+  proposerId: 'agent_main_001',
+  description: 'Analyze CSV file and generate summary statistics',
+  requiredCapability: CapabilityType.DATA_ANALYSIS,
+  input: {
+    filePath: '/data/sales.csv',
+    operations: ['mean', 'median', 'std']
+  },
+  maxLatency: 5000,
+  maxCost: 200,
+  priority: 7
+};
+
+const message = createTaskProposalMessage(proposal);
+websocket.send(JSON.stringify(message));
+```
+
+### 3. Submitting a Bid
+
+```typescript
+import { createTaskBidMessage, TaskBid } from './protocol';
+
+const bid: TaskBid = {
+  taskId: 'task_abc123',
+  bidderId: 'agent_data_001',
+  estimatedLatency: 3000,
+  estimatedCost: 150,
+  confidence: 0.95,
+  queueDepth: 2,
+  notes: 'Specialized in CSV analysis with pandas'
+};
+
+const message = createTaskBidMessage(bid, 'agent_data_001');
+websocket.send(JSON.stringify(message));
+```
+
+### 4. Context Transfer
+
+```typescript
+import { createContextTransferMessage, ContextTransfer } from './protocol';
+
+const transfer: ContextTransfer = {
+  fromAgent: 'agent_a',
+  toAgent: 'agent_b',
+  taskId: 'task_xyz789',
+  contextType: 'conversation_history',
+  data: {
+    messages: [
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi there!' }
+    ],
+    metadata: { sessionId: 'session_123' }
+  },
+  compression: 'none'
+};
+
+const message = createContextTransferMessage(transfer);
+websocket.send(JSON.stringify(message));
+```
+
+### 5. Message Validation
+
+```typescript
+import { validateIAPMessage, validateHandshake } from './protocol';
+
+// Validate complete message
+const result = validateIAPMessage(incomingMessage);
+if (!result.valid) {
+  console.error('Validation errors:', result.errors);
+}
+
+// Validate specific payload
+const handshakeResult = validateHandshake(handshakePayload);
+if (!handshakeResult.valid) {
+  console.error('Invalid handshake:', handshakeResult.errors);
+}
+```
+
+## State Management
+
+### Flow States
+
+The protocol defines a state machine for tracking agent and task states:
+
+```typescript
+enum FlowState {
+  DISCONNECTED = 'disconnected',
+  HANDSHAKING = 'handshaking',
+  CONNECTED = 'connected',
+  IDLE = 'idle',
+  DISCOVERING = 'discovering',
+  PROPOSING = 'proposing',
+  BIDDING = 'bidding',
+  ASSIGNING = 'assigning',
+  EXECUTING = 'executing',
+  TRANSFERRING_CONTEXT = 'transferring_context',
+  COMPLETING = 'completing',
+  ERROR = 'error',
+  DISCONNECTING = 'disconnecting'
+}
+```
+
+### Task Lifecycle
+
+```typescript
+enum TaskStatus {
+  PROPOSED = 'proposed',
+  BIDDING = 'bidding',
+  ASSIGNED = 'assigned',
+  IN_PROGRESS = 'in_progress',
+  COMPLETED = 'completed',
+  FAILED = 'failed',
+  CANCELLED = 'cancelled'
+}
+```
+
+### State Transitions
+
+```typescript
+import { 
+  createFlowContext, 
+  transitionFlow, 
+  MessageType 
+} from './protocol';
+
+// Create initial context
+const context = createFlowContext('agent_001');
+
+// Transition through states
+const newContext = transitionFlow(context, MessageType.HANDSHAKE);
+// context.currentState: DISCONNECTED -> HANDSHAKING
+```
+
+## Performance Considerations
+
+### Message Size
+
+- Keep payloads under 10KB for optimal performance
+- Use compression for larger context transfers
+- Consider chunking for very large data transfers
+
+### Latency Targets
+
+- **Handshake**: < 100ms
+- **Discovery**: < 50ms
+- **Task Assignment**: < 100ms
+- **Context Transfer**: < 200ms (depends on size)
+
+### Heartbeat Interval
+
+Recommended: 30 seconds
+- Balances connection monitoring with network overhead
+- Adjust based on network reliability
+
+## Error Handling
+
+### Error Codes
+
+| Code | Description | Recoverable |
+|------|-------------|-------------|
+| `VALIDATION_ERROR` | Message validation failed | Yes |
+| `CAPABILITY_NOT_FOUND` | Required capability unavailable | Yes |
+| `TASK_TIMEOUT` | Task execution exceeded deadline | No |
+| `AGENT_OVERLOAD` | Agent at maximum capacity | Yes |
+| `CONTEXT_TRANSFER_FAILED` | Context transfer failed | Yes |
+| `PROTOCOL_VERSION_MISMATCH` | Incompatible protocol versions | No |
+
+### Error Message Example
+
+```typescript
+import { createErrorMessage, ErrorMessage } from './protocol';
+
+const error: ErrorMessage = {
+  code: 'TASK_TIMEOUT',
+  message: 'Task execution exceeded 5000ms deadline',
+  relatedTaskId: 'task_abc123',
+  details: { actualLatency: 6500 },
+  recoverable: false
+};
+
+const message = createErrorMessage(
+  'agent_001',
+  'router',
+  error,
+  'msg_original_123'
+);
+```
+
+## Security Considerations
+
+### Authentication
+
+- Implement agent authentication at the WebSocket layer
+- Use JWT tokens or API keys for agent identification
+- Validate agent identity during handshake
+
+### Authorization
+
+- Enforce capability-based access control
+- Validate task permissions before assignment
+- Audit all agent actions
+
+### Data Protection
+
+- Encrypt sensitive data in context transfers
+- Use checksums to verify data integrity
+- Implement rate limiting to prevent abuse
+
+## Integration with Subconscious Router
+
+The I.A.P. protocol is designed to work seamlessly with the Subconscious Router's semantic caching:
+
+1. **Semantic Interception**: Router checks incoming tasks against vector database
+2. **Cache Hit**: Return cached result (< 50ms) without agent execution
+3. **Cache Miss**: Route to appropriate agent via I.A.P. negotiation
+4. **Result Caching**: Store result with embedding for future hits
+
+```typescript
+// Pseudo-code for router integration
+async function handleTaskProposal(proposal: TaskProposal) {
+  // Check semantic cache
+  const cached = await semanticCache.query(proposal.description);
+  
+  if (cached && cached.similarity > 0.95) {
+    // Instant response from cache
+    return cached.result;
+  }
+  
+  // Route via I.A.P. negotiation
+  const bids = await broadcastTaskProposal(proposal);
+  const winner = selectBestBid(bids);
+  const result = await assignAndExecute(winner, proposal);
+  
+  // Cache for future
+  await semanticCache.store(proposal.description, result);
+  
+  return result;
+}
+```
+
+## Framework Integration
+
+### LangChain
+
+```typescript
+import { LangChainAgent } from '@langchain/core';
+import { IAPClient } from './iap-client';
+
+const agent = new LangChainAgent(/* config */);
+const iapClient = new IAPClient('ws://router:8080');
+
+await iapClient.connect({
+  agentId: 'langchain_001',
+  name: 'LangChain Agent',
+  capabilities: agent.getCapabilities()
+});
+```
+
+### CrewAI
+
+```python
+from crewai import Agent
+from iap_client import IAPClient
+
+agent = Agent(role="researcher", goal="Research topics")
+iap_client = IAPClient("ws://router:8080")
+
+await iap_client.connect(
+    agent_id="crewai_001",
+    name="CrewAI Researcher",
+    capabilities=agent.get_capabilities()
+)
+```
+
+### AutoGPT
+
+```typescript
+import { AutoGPTAgent } from 'autogpt';
+import { IAPClient } from './iap-client';
+
+const agent = new AutoGPTAgent(/* config */);
+const iapClient = new IAPClient('ws://router:8080');
+
+await iapClient.connect({
+  agentId: 'autogpt_001',
+  name: 'AutoGPT Agent',
+  capabilities: agent.listCapabilities()
+});
+```
+
+## Versioning
+
+The protocol follows semantic versioning (MAJOR.MINOR.PATCH):
+
+- **MAJOR**: Breaking changes to message structure or flow
+- **MINOR**: New message types or optional fields
+- **PATCH**: Bug fixes and clarifications
+
+Current version: **1.0.0**
+
+### Version Compatibility
+
+- Agents must specify `protocolVersion` in handshake
+- Router validates version compatibility (same major version)
+- Incompatible versions receive `PROTOCOL_VERSION_MISMATCH` error
+
+## Future Enhancements
+
+### v1.1.0 (Planned)
+- Message batching for high-throughput scenarios
+- Streaming responses for long-running tasks
+- Agent reputation and trust scoring
+
+### v2.0.0 (Roadmap)
+- Direct agent-to-agent communication (bypass router)
+- Multi-router federation
+- Advanced consensus mechanisms
+
+## Contributing
+
+Contributions to the I.A.P. specification are welcome! Please submit issues and pull requests to the [GitHub repository](https://github.com/subconscious-router/iap).
+
+## License
+
+MIT License - See LICENSE file for details
+
+## References
+
+- [Subconscious Router Technical Specification](../../TECHNICAL_SPEC.md)
+- [WebSocket Protocol (RFC 6455)](https://tools.ietf.org/html/rfc6455)
+- [JSON Schema](https://json-schema.org/)
+- [Semantic Versioning](https://semver.org/)

package/src/proxy/ComplexityRouter.js

@@ -0,0 +1,37 @@
+// Complexity Router - Evaluates prompt complexity to optimize LLM cost
+class ComplexityRouter {
+  constructor() {
+    this.cheapModel = 'gpt-4o-mini';
+    this.complexKeywords = ['architecture', 'design', 'debug', 'trace', 'system', 'microservices', 'explain', 'why', 'refactor', 'optimize'];
+  }
+
+  evaluate(prompt, originalModel) {
+    if (!prompt || prompt.length < 10) return { model: this.cheapModel, complexity: 'low' };
+    
+    const lower = prompt.toLowerCase();
+    let isComplex = false;
+    
+    // Heuristic 1: Prompt Length
+    if (prompt.length > 500) {
+      isComplex = true;
+    }
+    
+    // Heuristic 2: Keywords that imply deep reasoning
+    for (const kw of this.complexKeywords) {
+      if (lower.includes(kw)) {
+        isComplex = true;
+        break;
+      }
+    }
+
+    if (isComplex) {
+      console.log(`[ComplexityRouter] High complexity detected. Routing to ${originalModel}`);
+      return { model: originalModel || 'gpt-4o', complexity: 'high' };
+    } else {
+      console.log(`[ComplexityRouter] Low complexity detected. Routing to ${this.cheapModel}`);
+      return { model: this.cheapModel, complexity: 'low' };
+    }
+  }
+}
+
+module.exports = ComplexityRouter;

package/src/security/SemanticScrubber.js

@@ -0,0 +1,54 @@
+// Privacy Firewall - Semantic Scrubber for PII and Secrets
+class SemanticScrubber {
+  constructor() {
+    this.patterns = [
+      { name: 'API_KEY', regex: /(sk-[a-zA-Z0-9\-]{20,})/g },
+      { name: 'EMAIL', regex: /([a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+\.[a-zA-Z0-9_-]+)/g },
+      { name: 'TOKEN', regex: /(Bearer\s+[a-zA-Z0-9\-._~+/]+=*)/gi }
+    ];
+  }
+
+  mask(prompt) {
+    let maskedPrompt = prompt;
+    const tokenMap = {};
+    let counter = 1;
+
+    for (const pattern of this.patterns) {
+      maskedPrompt = maskedPrompt.replace(pattern.regex, (match) => {
+        const token = `[${pattern.name}_${counter++}]`;
+        tokenMap[token] = match;
+        return token;
+      });
+    }
+
+    if (Object.keys(tokenMap).length > 0) {
+      console.log(`[PrivacyFirewall] Masked ${Object.keys(tokenMap).length} secrets.`);
+    }
+
+    return { maskedPrompt, tokenMap };
+  }
+
+  unmask(responseObj, tokenMap) {
+    if (!responseObj || Object.keys(tokenMap).length === 0) return responseObj;
+    
+    let str = typeof responseObj === 'string' ? responseObj : JSON.stringify(responseObj);
+    
+    for (const [token, value] of Object.entries(tokenMap)) {
+      str = str.split(token).join(value);
+    }
+    
+    return typeof responseObj === 'string' ? str : JSON.parse(str);
+  }
+  
+  // Unmask a single stream chunk string
+  unmaskString(str, tokenMap) {
+    if (!str || Object.keys(tokenMap).length === 0) return str;
+    let unmasked = str;
+    for (const [token, value] of Object.entries(tokenMap)) {
+      unmasked = unmasked.split(token).join(value);
+    }
+    return unmasked;
+  }
+}
+
+module.exports = SemanticScrubber;