@nebulaos/core 0.1.1

package/README.md

@@ -0,0 +1,206 @@
+# @starya/nebulaos-core
+
+The core of NebulaOS for building AI Agents and complex Workflows. This package provides the essential primitives for orchestration, state management, and model abstraction.
+
+## Installation
+
+```bash
+pnpm add @starya/nebulaos-core
+```
+
+---
+
+## ✨ Features Overview
+
+### 🤖 Agent System
+- ✅ **Multi-Step Reasoning** - Automatic tool calling loops with configurable max steps
+- ✅ **Streaming Support** - Real-time token streaming with `executeStream()`
+- ✅ **Tool Calling** - Function calling with Zod schema validation
+- ✅ **Parallel Tool Execution** - Execute multiple tools simultaneously
+- ✅ **Structured Outputs** - JSON mode with schema validation
+- ✅ **Memory Management** - Pluggable memory implementations (InMemory, Redis, etc.)
+- ✅ **Dynamic Instructions** - Support for async instruction resolution
+- ✅ **Request/Response Interceptors** - Middleware for RAG, sanitization, etc.
+- ✅ **Multimodal Support** - Text + Images (via ContentPart[])
+
+### 🔄 Workflow Orchestration
+- ✅ **Fluent API** - Declarative workflow definition (`.start().step().finish()`)
+- ✅ **Branching & Parallel** - Conditional paths and concurrent execution
+- ✅ **State Persistence** - Save/resume workflow state (requires state store)
+- ✅ **Retry Policies** - Exponential/Linear backoff with configurable attempts
+- ✅ **Input/Output Validation** - Zod schema validation at boundaries
+- ✅ **Queue Integration** - Async workflow execution (requires queue adapter)
+- ✅ **Event-Driven** - Lifecycle events for monitoring and logging
+
+### 📊 Observability & Tracing
+- ✅ **Distributed Tracing** - Automatic trace/span propagation via AsyncLocalStorage
+- ✅ **Event System** - Rich lifecycle events (`execution:start`, `llm:call`, `tool:result`, etc.)
+- ✅ **Correlation IDs** - Track requests across nested operations
+- ✅ **Structured Logging** - Beautiful console logs with ANSI colors and metadata trees
+- ✅ **Log Levels** - Configurable (debug, info, warn, error)
+- ✅ **Custom Loggers** - Implement `ILogger` for Datadog, CloudWatch, etc.
+- ✅ **PII Masking** - GDPR/LGPD compliance with pluggable masking
+
+### 🧪 Testing & Quality
+- ✅ **Provider Compliance Suite** - Reusable test suite for model providers
+- ✅ **Mock Implementations** - MockProvider, MockStateStore for unit tests
+- ✅ **Integration Tests** - Live API tests with real providers
+- ✅ **Type Safety** - Full TypeScript support with strict typing
+- ✅ **Test Coverage** - Comprehensive unit and integration tests
+
+### 🔌 Provider System
+- ✅ **Provider Abstraction** - IModel interface for any LLM (OpenAI, Anthropic, etc.)
+- ✅ **Token Usage Tracking** - Automatic accumulation across multi-step flows
+- ✅ **Streaming Protocol** - Unified chunk types (content_delta, tool_call_start, etc.)
+- ✅ **Error Handling** - Graceful degradation and retry logic
+
+---
+
+## 🆕 Recent Updates
+
+### v0.0.1 - Distributed Tracing & Stream Parity
+- **Distributed Tracing**: Automatic trace/span propagation across Agent → Workflow → Tool chains
+- **executeStream() Parity**: Full feature parity with execute() including token tracking, events, and max steps fallback
+- **Enhanced Logging**: Color-coded terminal output with hierarchical metadata display
+- **Response Interceptors**: Now run only on final responses (not intermediate tool calls)
+- **Test Coverage**: Expanded to 22 unit tests + 7 integration tests
+
+---
+
+## Core Components
+
+### 1. Agent (`Agent`)
+
+The main class that manages the lifecycle of AI interaction.
+
+### Key Features
+*   **Memory-First**: Every agent requires a memory implementation (e.g., `InMemory`) to maintain context.
+*   **Interceptors**: Middleware to modify requests and responses.
+    *   **Request Interceptors**: Run before each LLM call. Useful for context injection (RAG).
+    *   **Response Interceptors**: Run **only on the final response** (or when there are no tool calls), ideal for output sanitization and formatting.
+*   **Streaming**: Native support for text and tool call streaming.
+*   **Observability**: Integrated event-based logging system with PII Masking support (GDPR/LGPD).
+
+### Complete Example
+
+```typescript
+import { Agent, InMemory, Tool, z } from "@starya/nebulaos-core";
+import { OpenAI } from "@starya/nebulaos-openai";
+
+// 1. Tools
+const calculator = new Tool({
+  id: "calculator",
+  description: "Adds two numbers",
+  inputSchema: z.object({ a: z.number(), b: z.number() }),
+  handler: async (ctx, input) => ({ result: input.a + input.b })
+});
+
+// 2. Agent
+const agent = new Agent({
+  name: "financial-assistant",
+  model: new OpenAI({
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: "gpt-4o"
+  }),
+  memory: new InMemory(),
+  instructions: "You help with financial calculations.",
+  tools: [calculator],
+  logLevel: "info", // Detailed console logs
+  interceptors: {
+    response: [
+        async (res) => {
+            // Format final output to uppercase (example)
+            if (res.content) res.content = res.content.toUpperCase();
+            return res;
+        }
+    ]
+  }
+});
+
+// 3. Execution
+await agent.addMessage({ role: "user", content: "How much is 10 + 20?" });
+const result = await agent.execute();
+console.log(result.content);
+```
+
+---
+
+## 🔄 Workflow (`Workflow`)
+
+Orchestrator for long-running and complex processes, supporting persistence, retries, and validation.
+
+### Features
+*   **Fluent API**: Declarative definition (`.start().step().branch().finish()`).
+*   **State Persistence**: Saves the state of each step (requires `stateStore`).
+*   **Resilience**: Configurable Retry Policies (Exponential, Linear).
+*   **Type-Safe**: Input and output validation with Zod.
+
+### Workflow Example
+
+```typescript
+import { Workflow, MockStateStore } from "@starya/nebulaos-core";
+import { z } from "zod";
+
+const workflow = new Workflow({
+  id: "order-processing",
+  stateStore: new MockStateStore(), // Or real implementation (Redis/Postgres)
+  retryPolicy: {
+      maxAttempts: 3,
+      backoff: "exponential",
+      initialDelay: 1000
+  }
+})
+.start(async ({ input }) => {
+    console.log("Validating order", input);
+    return input;
+})
+.step("payment", async ({ input }) => {
+    // Payment logic
+    return { status: "paid", id: input.id };
+})
+.finish(async ({ input }) => {
+    return { message: `Order ${input.id} processed successfully` };
+});
+
+// Execution
+const result = await workflow.run({ id: 123, total: 500 });
+```
+
+---
+
+## 🛡️ Logging & Observability
+
+The Core emits rich events during execution (`execution:start`, `llm:call`, `tool:result`).
+
+### Configuration
+The default logger (`ConsoleLogger`) can be configured via `logLevel`. For production, you can implement the `ILogger` interface to send logs to Datadog, CloudWatch, etc.
+
+### PII Masking (Privacy)
+Protect sensitive data in logs by configuring a `piiMasker`.
+
+```typescript
+const agent = new Agent({
+  // ...
+  piiMasker: {
+      mask: (text) => text.replace(/\d{3}\.\d{3}\.\d{3}-\d{2}/g, "***") // Example mask
+  }
+});
+```
+
+---
+
+## 🧪 Testing & Compliance
+
+### Package Tests
+```bash
+pnpm test
+```
+
+### Provider Compliance Suite
+If you are creating a new Provider (e.g., Anthropic), use the compliance suite to ensure full compatibility.
+
+```typescript
+import { runProviderComplianceTests } from "@starya/nebulaos-core/test-utils";
+
+runProviderComplianceTests(() => new MyNewProvider(...), { runLiveTests: true });
+```

package/dist/__tests__/mocks/mock-provider.d.ts

@@ -0,0 +1,15 @@
+import { IModel, Message, ProviderResponse, StreamChunk, ToolDefinitionForLLM, GenerateOptions } from "../../agent/provider";
+export declare class MockProvider implements IModel {
+    providerName: string;
+    modelName: string;
+    responses: ProviderResponse[];
+    streams: StreamChunk[][];
+    calls: {
+        messages: Message[];
+        tools?: ToolDefinitionForLLM[];
+    }[];
+    enqueueResponse(response: Partial<ProviderResponse>): void;
+    enqueueStream(chunks: StreamChunk[]): void;
+    generate(messages: Message[], tools?: ToolDefinitionForLLM[], options?: GenerateOptions): Promise<ProviderResponse>;
+    generateStream(messages: Message[], tools?: ToolDefinitionForLLM[], options?: GenerateOptions): AsyncGenerator<StreamChunk>;
+}

package/dist/__tests__/mocks/mock-provider.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MockProvider = void 0;
+class MockProvider {
+    providerName = "mock";
+    modelName = "mock-model";
+    responses = [];
+    streams = [];
+    calls = [];
+    enqueueResponse(response) {
+        this.responses.push({
+            content: "",
+            usage: { promptTokens: 10, completionTokens: 10, totalTokens: 20 },
+            finishReason: "stop",
+            ...response
+        });
+    }
+    enqueueStream(chunks) {
+        this.streams.push(chunks);
+    }
+    async generate(messages, tools, options) {
+        this.calls.push({ messages, tools });
+        const response = this.responses.shift();
+        if (!response) {
+            // Default response if none enqueued
+            return {
+                content: "Mock default response",
+                finishReason: "stop",
+                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
+            };
+        }
+        return response;
+    }
+    async *generateStream(messages, tools, options) {
+        this.calls.push({ messages, tools });
+        const chunks = this.streams.shift();
+        if (!chunks)
+            throw new Error("MockProvider: No stream enqueued");
+        for (const chunk of chunks) {
+            yield chunk;
+        }
+    }
+}
+exports.MockProvider = MockProvider;

package/dist/agent/Agent.d.ts

@@ -0,0 +1,96 @@
+import { IModel, Message, ToolCall, StreamChunk, ProviderResponse, ContentPart } from "./provider/index.js";
+import { IMemory, MemoryExecutionContext } from "./memory/index.js";
+import { Tool, ToolExecution } from "./tools/index.js";
+import { ISkill } from "./skills/index.js";
+import { IPIIMasker } from "../lgpd/index.js";
+import { ILogger, LogLevel } from "../logger/index.js";
+import { BaseAgent } from "./BaseAgent.js";
+import type { IHttpClient } from "@nebulaos/types";
+export interface IInstruction {
+    resolve(): Promise<string>;
+}
+export type AgentInstruction = string | IInstruction;
+export interface AgentRequestContext {
+    messages: Message[];
+    tools: Tool[];
+}
+export type RequestInterceptor = (context: AgentRequestContext) => Promise<AgentRequestContext>;
+export type ResponseInterceptor = (response: ProviderResponse) => Promise<ProviderResponse>;
+export type AgentConfig = {
+    id: string;
+    name: string;
+    model: IModel;
+    memory: IMemory;
+    instructions: AgentInstruction;
+    tools?: Tool[];
+    skills?: ISkill[];
+    maxSteps?: number;
+    piiMasker?: IPIIMasker;
+    interceptors?: {
+        request?: RequestInterceptor[];
+        response?: ResponseInterceptor[];
+    };
+    logger?: ILogger;
+    logLevel?: LogLevel;
+};
+export type AgentExecuteOptions = {
+    responseFormat?: {
+        type: "json";
+        schema?: Record<string, any>;
+    };
+    maxSteps?: number;
+    disableTools?: boolean;
+    executionId?: string;
+    /** Memory partition key. When provided, memory operations are scoped to this key. */
+    memoryKey?: string;
+};
+export type AgentResult = {
+    content: any;
+    toolExecutions: ToolExecution[];
+    toolCalls?: ToolCall[];
+    llmCalls: number;
+    totalDurationMs: number;
+    truncated: boolean;
+};
+export type AgentStreamChunk = StreamChunk | {
+    type: "tool_result";
+    toolCallId: string;
+    result: any;
+} | {
+    type: "error";
+    error: any;
+};
+export declare class Agent extends BaseAgent {
+    config: AgentConfig;
+    private resolvedInstructions?;
+    private requestInterceptors;
+    private responseInterceptors;
+    private loggerAdapter;
+    private skillsInitialized;
+    private httpClient?;
+    constructor(config: AgentConfig);
+    /**
+     * Sets the HTTP client for tool execution context.
+     * This is typically called by the client package with InstrumentedHttpClient.
+     */
+    setHttpClient(client: IHttpClient): void;
+    private initializeSkills;
+    private resolveInstructions;
+    private isInstruction;
+    clearInstructionsCache(): void;
+    addMessage(message: Message, ctx?: MemoryExecutionContext): Promise<void>;
+    private getMessagesWithContext;
+    execute(options?: AgentExecuteOptions): Promise<AgentResult>;
+    execute(input?: string, options?: AgentExecuteOptions): Promise<AgentResult>;
+    execute(input?: ContentPart[], options?: AgentExecuteOptions): Promise<AgentResult>;
+    executeStream(options?: AgentExecuteOptions): AsyncGenerator<AgentStreamChunk>;
+    private executeToolCall;
+    private safeParseJson;
+    private validateMessagesForModel;
+    private mimeTypeMatches;
+    /**
+     * Estimates the decoded byte length of a base64 string without decoding it.
+     */
+    private estimateBase64Bytes;
+    private finishResult;
+}