@nebulaos/core 0.1.1

package/dist/agent/provider/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Core Provider Interfaces
+ *
+ * Define o contrato que qualquer provedor de LLM (OpenAI, Anthropic, etc.)
+ * deve implementar para ser compatível com o Agent.
+ */
+export type Role = "system" | "user" | "assistant" | "function" | "tool";
+export type ToolCall = {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+    /** Gemini thought signature - must be preserved for Gemini 3+ models */
+    thought_signature?: string;
+};
+export type FileSource = {
+    type: "url";
+    url: string;
+    sizeBytes?: number;
+} | {
+    type: "base64";
+    base64: string;
+};
+export type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "file";
+    file: {
+        /** Optional display name (e.g., "invoice.pdf") */
+        name?: string;
+        /** MIME type (e.g., "application/pdf", "image/png") */
+        mimeType: string;
+        source: FileSource;
+    };
+} | {
+    /** Direct image URL format (compatible with OpenAI API) */
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+};
+export type Message = {
+    role: Role;
+    content?: string | ContentPart[] | null;
+    name?: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+};
+export type TokenUsage = {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    reasoningTokens?: number;
+};
+export type ToolDefinitionForLLM = {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, any>;
+    };
+};
+export type ResponseFormat = {
+    type: "text";
+} | {
+    type: "json";
+    schema?: Record<string, any>;
+};
+export type ProviderResponse = {
+    content: string | null;
+    toolCalls?: ToolCall[];
+    usage?: TokenUsage;
+    finishReason?: "stop" | "length" | "tool_calls" | "content_filter" | "error";
+};
+export type StreamChunk = {
+    type: "content_delta";
+    delta: string;
+} | {
+    type: "tool_call_start";
+    index: number;
+    id: string;
+    name: string;
+    thought_signature?: string;
+} | {
+    type: "tool_call_delta";
+    index: number;
+    args: string;
+} | {
+    type: "tool_call_end";
+    index: number;
+} | {
+    type: "finish";
+    reason: ProviderResponse["finishReason"];
+    usage?: TokenUsage;
+} | {
+    type: "error";
+    error: Error;
+};
+export interface GenerateOptions {
+    responseFormat?: ResponseFormat;
+    [key: string]: any;
+}
+export interface ModelCapabilities {
+    /**
+     * File inputs supported by the model/provider.
+     * If omitted, the model is assumed to NOT support file parts.
+     */
+    inputFiles?: {
+        /** Accepted MIME types (exact matches or wildcard like "image/*") */
+        mimeTypes: readonly string[] | "any";
+        /** Accepted source types */
+        sources: ReadonlyArray<FileSource["type"]>;
+    };
+}
+export interface IModel {
+    providerName: string;
+    modelName: string;
+    capabilities?: ModelCapabilities;
+    /**
+     * Gera uma resposta completa (não-streaming)
+     */
+    generate(messages: Message[], tools?: ToolDefinitionForLLM[], options?: GenerateOptions): Promise<ProviderResponse>;
+    /**
+     * Gera uma resposta em streaming
+     */
+    generateStream(messages: Message[], tools?: ToolDefinitionForLLM[], options?: GenerateOptions): AsyncGenerator<StreamChunk>;
+}

package/dist/agent/provider/index.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Core Provider Interfaces
+ *
+ * Define o contrato que qualquer provedor de LLM (OpenAI, Anthropic, etc.)
+ * deve implementar para ser compatível com o Agent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/agent/skills/index.d.ts

@@ -0,0 +1,61 @@
+import { Tool } from "../tools/index.js";
+/**
+ * Interface that all skills must implement.
+ *
+ * Skills are modular extensions that add tools and optionally modify
+ * agent instructions. They encapsulate reusable functionality that can
+ * be easily added to agents.
+ *
+ * @example
+ * ```typescript
+ * class MySkill implements ISkill {
+ *   async getTools(): Promise<Tool[]> {
+ *     return [
+ *       new Tool({
+ *         id: "my_tool",
+ *         description: "Does something useful",
+ *         inputSchema: z.object({ query: z.string() }),
+ *         handler: async (ctx, input) => {
+ *           return { result: "..." };
+ *         }
+ *       })
+ *     ];
+ *   }
+ *
+ *   async initialize?(): Promise<void> {
+ *     // Optional: Setup code, validate config, etc.
+ *   }
+ *
+ *   getInstructions?(): string {
+ *     // Optional: Add skill-specific instructions
+ *     return "When using my_tool, remember to...";
+ *   }
+ * }
+ * ```
+ */
+export interface ISkill {
+    /**
+     * Returns the tools provided by this skill.
+     * This method is called during agent initialization.
+     *
+     * @returns Array of Tool instances that this skill provides
+     */
+    getTools(): Promise<Tool[]> | Tool[];
+    /**
+     * Optional initialization method.
+     * Called once when the agent is constructed, before tools are registered.
+     * Use this for validation, setup, or any async initialization.
+     */
+    initialize?(): Promise<void>;
+    /**
+     * Optional method to provide additional instructions for the agent.
+     * These instructions will be appended to the agent's main instructions.
+     *
+     * @returns Additional instructions text for the agent
+     */
+    getInstructions?(): string | Promise<string>;
+}
+/**
+ * Helper function to validate that an object implements ISkill
+ */
+export declare function isSkill(obj: any): obj is ISkill;

package/dist/agent/skills/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSkill = isSkill;
+/**
+ * Helper function to validate that an object implements ISkill
+ */
+function isSkill(obj) {
+    return obj && typeof obj.getTools === "function";
+}

package/dist/agent/tools/index.d.ts

@@ -0,0 +1,35 @@
+import { ZodSchema } from "zod";
+import { ToolDefinitionForLLM } from "../provider/index.js";
+export type ToolConfig<Input = any, Output = any> = {
+    /** Tool identifier (used as function name for LLM) */
+    id: string;
+    description?: string;
+    /** Zod schema for input validation */
+    inputSchema?: ZodSchema<Input>;
+    /** Alias for inputSchema (for backwards compatibility) */
+    parameters?: ZodSchema<Input>;
+    handler?: (ctx: any, input: Input) => Promise<Output>;
+};
+export type ToolExecution = {
+    id: string;
+    name: string;
+    input: any;
+    output: any;
+    durationMs: number;
+    error?: string;
+};
+export declare class Tool<Input = any, Output = any> {
+    readonly id: string;
+    readonly description?: string;
+    readonly inputSchema?: ZodSchema<Input>;
+    private handler?;
+    constructor(config: ToolConfig<Input, Output>);
+    /**
+     * Converte a tool para o formato esperado pelo LLM
+     */
+    toLLMDefinition(): ToolDefinitionForLLM;
+    /**
+     * Executa a tool com validação de input
+     */
+    execute(context: any, input: any): Promise<Output>;
+}

package/dist/agent/tools/index.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tool = void 0;
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+// Helper to convert Zod/JSON schema to OpenAI format
+function toJsonSchema(input) {
+    const defaultSchema = { type: "object", properties: {}, required: [] };
+    if (input && typeof input === "object" && "_def" in input) {
+        try {
+            const schema = (0, zod_to_json_schema_1.zodToJsonSchema)(input, {
+                $refStrategy: "none",
+                target: "openApi3",
+            });
+            return {
+                type: "object",
+                properties: schema.properties ?? {},
+                required: schema.required ?? [],
+            };
+        }
+        catch {
+            return defaultSchema;
+        }
+    }
+    if (input && typeof input === "object" && "type" in input) {
+        const obj = input;
+        return {
+            type: "object",
+            properties: obj.properties ?? {},
+            required: obj.required ?? [],
+        };
+    }
+    return defaultSchema;
+}
+class Tool {
+    id;
+    description;
+    inputSchema;
+    handler;
+    constructor(config) {
+        this.id = config.id;
+        this.description = config.description;
+        // Accept both inputSchema and parameters (parameters is alias)
+        this.inputSchema = config.inputSchema ?? config.parameters;
+        this.handler = config.handler;
+    }
+    /**
+     * Converte a tool para o formato esperado pelo LLM
+     */
+    toLLMDefinition() {
+        return {
+            type: "function",
+            function: {
+                name: this.id,
+                description: this.description,
+                parameters: this.inputSchema ? toJsonSchema(this.inputSchema) : undefined,
+            },
+        };
+    }
+    /**
+     * Executa a tool com validação de input
+     */
+    async execute(context, input) {
+        let parsedInput = input;
+        // Validate input if schema is present
+        if (this.inputSchema) {
+            // If input is string (JSON), parse it first
+            if (typeof input === "string") {
+                try {
+                    parsedInput = JSON.parse(input);
+                }
+                catch {
+                    throw new Error(`Invalid JSON input for tool ${this.id}`);
+                }
+            }
+            const result = this.inputSchema.safeParse(parsedInput);
+            if (!result.success) {
+                throw new Error(`Invalid input for tool ${this.id}: ${result.error.message}`);
+            }
+            parsedInput = result.data;
+        }
+        if (this.handler) {
+            return this.handler(context, parsedInput);
+        }
+        throw new Error(`Tool ${this.id} has no handler implementation.`);
+    }
+}
+exports.Tool = Tool;

package/dist/cost/add-cost.d.ts

@@ -0,0 +1,10 @@
+export interface AddCostInput {
+    amount: number | string;
+    description?: string;
+    source?: string;
+    idempotencyKey?: string;
+    metadata?: Record<string, unknown>;
+    timestamp?: Date | string;
+    correlationId?: string;
+}
+export declare function addCost(input: AddCostInput): void;

package/dist/cost/add-cost.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addCost = addCost;
+const node_crypto_1 = require("node:crypto");
+const index_js_1 = require("../domain-events/index.js");
+const index_js_2 = require("../execution-context/index.js");
+const index_js_3 = require("../tracing/index.js");
+function addCost(input) {
+    const execContext = index_js_2.ExecutionContext.getOrUndefined();
+    if (!execContext) {
+        throw new Error("addCost must be called inside an execution context");
+    }
+    const amount = normalizeAmount(input.amount);
+    const timestamp = normalizeTimestamp(input.timestamp);
+    const traceContext = index_js_3.Tracing.getContext();
+    const payload = {
+        amount,
+        description: input.description,
+        source: input.source,
+        idempotencyKey: normalizeIdempotencyKey({
+            executionId: execContext.executionId,
+            traceId: traceContext?.traceId,
+            spanId: traceContext?.spanId,
+            timestamp,
+            amount,
+            description: input.description,
+            source: input.source,
+            metadata: input.metadata,
+        }, input.idempotencyKey),
+        metadata: input.metadata,
+    };
+    const fullEvent = {
+        type: "execution:cost:incurred",
+        timestamp,
+        trace: {
+            traceId: traceContext?.traceId ?? `fallback-${Date.now()}`,
+            spanId: traceContext?.spanId ?? `fallback-${Date.now()}`,
+            parentSpanId: traceContext?.parentId,
+        },
+        correlationId: input.correlationId,
+        executionId: execContext.executionId,
+        rootExecutionId: execContext.rootExecutionId,
+        parentExecutionId: execContext.parentExecutionId,
+        data: payload,
+    };
+    index_js_1.DomainEvents.publish(fullEvent);
+}
+function normalizeAmount(value) {
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("addCost amount must be a finite number");
+        }
+        return value.toString();
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new Error("addCost amount is required");
+    }
+    const parsed = Number(trimmed);
+    if (!Number.isFinite(parsed)) {
+        throw new Error("addCost amount must be numeric");
+    }
+    return trimmed;
+}
+function normalizeTimestamp(value) {
+    if (!value)
+        return new Date().toISOString();
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new Error("addCost timestamp is invalid");
+    }
+    return date.toISOString();
+}
+function normalizeIdempotencyKey(payload, provided) {
+    const trimmed = provided?.trim();
+    if (trimmed)
+        return trimmed;
+    const raw = JSON.stringify(payload);
+    return (0, node_crypto_1.createHash)("sha256").update(raw).digest("hex");
+}

package/dist/cost/add-cost.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cost/add-cost.spec.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const add_cost_js_1 = require("./add-cost.js");
+const index_js_1 = require("../domain-events/index.js");
+const index_js_2 = require("../execution-context/index.js");
+const schemas_js_1 = require("../events/schemas.js");
+class CapturingExporter {
+    events = [];
+    async exportBatch(events) {
+        this.events.push(...events);
+    }
+}
+describe("addCost", () => {
+    it("should publish a valid execution cost event using context ids", async () => {
+        const exporter = new CapturingExporter();
+        index_js_1.DomainEvents.setExporter(exporter);
+        await index_js_2.ExecutionContext.run({ executionId: "exec-123", rootExecutionId: "exec-123" }, async () => {
+            (0, add_cost_js_1.addCost)({ amount: 0.05, description: "LLM usage" });
+        });
+        expect(exporter.events.length).toBe(1);
+        const event = exporter.events[0];
+        const parsed = schemas_js_1.NebulaEventSchema.safeParse(event);
+        expect(parsed.success).toBe(true);
+        if (!parsed.success)
+            return;
+        expect(parsed.data.type).toBe("execution:cost:incurred");
+        const costEvent = parsed.data;
+        expect(costEvent.executionId).toBe("exec-123");
+        expect(costEvent.rootExecutionId).toBe("exec-123");
+        expect(costEvent.data.amount).toBe("0.05");
+        expect(costEvent.data.description).toBe("LLM usage");
+    });
+    it("should throw when called outside execution context", () => {
+        expect(() => (0, add_cost_js_1.addCost)({ amount: "1" })).toThrow("addCost must be called inside an execution context");
+    });
+});

package/dist/cost/index.d.ts

@@ -0,0 +1 @@
+export * from "./add-cost.js";

package/dist/cost/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./add-cost.js"), exports);

package/dist/domain-events/index.d.ts

@@ -0,0 +1,16 @@
+import type { NebulaEvent } from "../events/schemas.js";
+export interface IDomainEventsExporter {
+    exportBatch(events: NebulaEvent[]): Promise<void>;
+}
+/**
+ * Best-effort domain event exporter.
+ *
+ * Observability (spans) is handled by `Tracing` and `ITelemetryExporter`.
+ * Domain events are separate and meant for materialization / execution indexing.
+ */
+export declare class DomainEvents {
+    private static exporter;
+    static setExporter(exporter: IDomainEventsExporter): void;
+    static publish(event: NebulaEvent): void;
+    static publishBatch(events: NebulaEvent[]): void;
+}

package/dist/domain-events/index.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DomainEvents = void 0;
+class NoopDomainEventsExporter {
+    async exportBatch(_events) {
+        // noop
+    }
+}
+/**
+ * Best-effort domain event exporter.
+ *
+ * Observability (spans) is handled by `Tracing` and `ITelemetryExporter`.
+ * Domain events are separate and meant for materialization / execution indexing.
+ */
+class DomainEvents {
+    static exporter = new NoopDomainEventsExporter();
+    static setExporter(exporter) {
+        this.exporter = exporter;
+    }
+    static publish(event) {
+        // Fire-and-forget; must never break execution paths.
+        try {
+            void this.exporter.exportBatch([event]);
+        }
+        catch {
+            // ignore
+        }
+    }
+    static publishBatch(events) {
+        try {
+            void this.exporter.exportBatch(events);
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+exports.DomainEvents = DomainEvents;

package/dist/eval/index.d.ts

@@ -0,0 +1,19 @@
+export type EvaluationResult = {
+    score: number;
+    passed: boolean;
+    reason?: string;
+    metadata?: Record<string, any>;
+};
+export interface IScorer {
+    name: string;
+    evaluate(input: string, output: string, expected?: string): Promise<EvaluationResult>;
+}
+/**
+ * Exemplo simples de Scorer: Valida se o output contém certas palavras-chave
+ */
+export declare class KeywordScorer implements IScorer {
+    private keywords;
+    name: string;
+    constructor(keywords: string[]);
+    evaluate(input: string, output: string): Promise<EvaluationResult>;
+}

package/dist/eval/index.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeywordScorer = void 0;
+/**
+ * Exemplo simples de Scorer: Valida se o output contém certas palavras-chave
+ */
+class KeywordScorer {
+    keywords;
+    name = "KeywordScorer";
+    constructor(keywords) {
+        this.keywords = keywords;
+    }
+    async evaluate(input, output) {
+        const lowerOutput = output.toLowerCase();
+        const found = this.keywords.filter(k => lowerOutput.includes(k.toLowerCase()));
+        const score = found.length / this.keywords.length;
+        return {
+            score,
+            passed: score === 1,
+            reason: `Found ${found.length}/${this.keywords.length} keywords: ${found.join(", ")}`,
+        };
+    }
+}
+exports.KeywordScorer = KeywordScorer;

package/dist/events/base.d.ts

@@ -0,0 +1,5 @@
+import type { TraceContext } from "./schemas.js";
+export interface NebulaEvent {
+    timestamp: string;
+    trace?: TraceContext;
+}

package/dist/events/base.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });