npm install @siglo/core @siglo/ai @siglo/http

import { flow } from '@siglo/core';
import { aiStep } from '@siglo/ai';

export const safeAiStep = aiStep('generateInsight', {
    model: { provider: 'openai', model: 'gpt-4o' },
    prompt: 'Analyze system telemetry.',
});

// Enclosing workflow network policy governs the step:
export const secureFlow = flow(safeAiStep).networkPolicy({
    allowedHosts: ['api.openai.com'],
});

import { z } from 'zod';
import { aiStep } from '@siglo/ai';

const AnalysisSchema = z.object({
    sentiment: z.enum(['POSITIVE', 'NEUTRAL', 'NEGATIVE']),
    score: z.number().min(0).max(1),
    tags: z.array(z.string()),
});

export const analyzeStep = aiStep('analyze', {
    model: { provider: 'openai', model: 'gpt-4o' },
    schema: AnalysisSchema,
    jsonSchema: z.toJSONSchema(AnalysisSchema),
    prompt: (ctx: { review: string }) => `Analyze this review: ${ctx.review}`,
});

// Downstream step receives fully typed ctx.data:
// ctx.data.sentiment -> 'POSITIVE' | 'NEUTRAL' | 'NEGATIVE'
// ctx.data.score -> number
// ctx.data.tags -> string[]

export const legacyStep = aiStep('legacyAnalysis', {
    model: { provider: 'ollama', model: 'llama3' },
    schema: AnalysisSchema,
    enforceNativeStructuredOutputs: false, // Disables native schema; relies on prompt & local validator
    prompt: 'Output JSON matching the schema.',
});

[System] You previously emitted invalid JSON that failed the required schema.
[Assistant] { "sentiment": "VERY_GOOD", "score": "high" }
[User] Your previous output failed validation. Return ONLY corrected JSON.
Validation diagnostics: [
  { "path": "sentiment", "message": "Invalid enum value. Expected 'POSITIVE' | 'NEUTRAL' | 'NEGATIVE'" },
  { "path": "score", "message": "Expected number, received string" }
]

export const resilientStep = aiStep('resilientSummary', {
    model: {
        provider: 'anthropic',
        model: 'claude-3-5-sonnet-20241022',
        requestTimeoutMs: 15_000,
    },
    fallbackModels: [
        { provider: 'openai', model: 'gpt-4o', requestTimeoutMs: 10_000 },
        { provider: 'gemini', model: 'gemini-2.0-flash', requestTimeoutMs: 10_000 },
    ],
    prompt: (ctx: { text: string }) => `Summarize: ${ctx.text}`,
});

import { Step } from '@siglo/core';
import { defineAiTool, aiStep } from '@siglo/ai';
import { z } from 'zod';

const bookingArgs = z.object({ roomId: z.string(), nights: z.number() });

const bookRoomStep = Step.create('bookRoom', async ({ roomId, nights }: { roomId: string; nights: number }) => {
    const reservation = await reservationService.book(roomId, nights);
    return { reservationId: reservation.id };
}).compensate(async ctx => {
    // Saga compensation rollback!
    await reservationService.cancel(ctx.reservationId);
});

export const bookRoomTool = defineAiTool({
    name: 'bookRoom',
    description: 'Reserve a hotel room for a guest',
    inputSchema: bookingArgs,
    jsonSchema: z.toJSONSchema(bookingArgs),
    mapInput: (args, ctx) => ({ roomId: args.roomId, nights: args.nights }),
    step: bookRoomStep,
});

export const cachedSummaryStep = aiStep('cachedSummary', {
    model: { provider: 'openai', model: 'gpt-4o' },
    prompt: (ctx: { documentId: string; content: string }) => `Summarize: ${ctx.content}`,
    cacheVersion: 'v1',
}).cache({ ttl: 3600 });

import { flow } from '@siglo/core';
import { WorkflowHarness } from '@siglo/testing';
import { MockAiProvider } from '@siglo/ai/testing';
import { aiStep } from '@siglo/ai';
import { z } from 'zod';

const schema = z.object({ summary: z.string() });

// Scripted mock provider (simulates a malformed response followed by a valid repair)
const mock = new MockAiProvider([
    { text: 'malformed json', promptTokens: 20, completionTokens: 5 },
    { text: '{"summary":"Workflow completed successfully"}', promptTokens: 30, completionTokens: 10 },
]);

const step = aiStep('summarize', {
    model: { provider: 'openai', model: 'gpt-4o', adapter: mock },
    schema,
    jsonSchema: z.toJSONSchema(schema),
    prompt: 'Summarize report',
});

const harness = new WorkflowHarness(flow(step));
const result = await harness.run({});

mock.assertDone(); // Asserts all mock responses were consumed
console.log(result.data.summary); // 'Workflow completed successfully'
console.log(result.$steps.summarize.aiMetrics.repairAttempts); // 1

const recording = mock.exportRecording();
const replayAdapter = MockAiProvider.replay(recording);

import { flow, Step } from '@siglo/core';
import { aiStep } from '@siglo/ai';
import { z } from 'zod';

const UnderwritingSchema = z.object({
    decision: z.enum(['APPROVE', 'MANUAL_REVIEW', 'DECLINE']),
    riskTier: z.enum(['LOW', 'MEDIUM', 'HIGH', 'PROHIBITIVE']),
    maxApprovedLimit: z.number().min(0),
    conditions: z.array(z.string()),
    rationale: z.string(),
});

interface LoanApplication {
    applicantId: string;
    applicantName: string;
    creditScore: number;
    requestedAmount: number;
    monthlyDebt: number;
    monthlyIncome: number;
}

export const underwriteLoanStep = aiStep('underwriteLoan', {
    model: {
        provider: 'anthropic',
        model: 'claude-3-5-sonnet-20241022',
        requestTimeoutMs: 12_000,
    },
    fallbackModels: [
        { provider: 'openai', model: 'gpt-4o', requestTimeoutMs: 10_000 },
        { provider: 'gemini', model: 'gemini-2.0-flash', requestTimeoutMs: 8_000 },
    ],
    temperature: 0.1,
    schema: UnderwritingSchema,
    jsonSchema: z.toJSONSchema(UnderwritingSchema),
    maxRepairAttempts: 2,
    prompt: (ctx: LoanApplication) => [
        {
            role: 'system',
            content:
                'You are a senior credit underwriter. Make risk assessments strictly based on debt-to-income and credit score.',
        },
        {
            role: 'user',
            content: `Applicant: ${ctx.applicantName} (ID: ${ctx.applicantId})
Credit Score: ${ctx.creditScore}
Requested: $${ctx.requestedAmount}
Monthly Debt: $${ctx.monthlyDebt}
Monthly Income: $${ctx.monthlyIncome}`,
        },
    ],
});

export const loanWorkflow = flow(
    underwriteLoanStep,
    Step.create('notifyApplicant', async ctx => {
        // TypeScript guarantees ctx.data contains decision, riskTier, etc.
        return { status: 'notified', decision: ctx.data.decision };
    }),
);

import { flow, Step } from '@siglo/core';
import { aiStep, defineAiTool } from '@siglo/ai';
import { z } from 'zod';

// Step 1: Customer Portfolio Lookup Step
const portfolioArgs = z.object({ customerId: z.string() });
const lookupPortfolioStep = Step.create('lookupPortfolio', async ({ customerId }: { customerId: string }) => {
    return { netWorth: 250_000, riskTolerance: 'MODERATE', holdings: ['VTI', 'BND'] };
});

const lookupPortfolioTool = defineAiTool({
    name: 'lookupPortfolio',
    description: 'Lookup customer investment portfolio and risk tolerance',
    inputSchema: portfolioArgs,
    jsonSchema: z.toJSONSchema(portfolioArgs),
    mapInput: args => args,
    step: lookupPortfolioStep,
});

// Step 2: Trade Allocation Step with Compensation
const tradeArgs = z.object({ symbol: z.string(), action: z.enum(['BUY', 'SELL']), amountUsd: z.number() });
const executeTradeStep = Step.create(
    'executeTrade',
    async ({ symbol, action, amountUsd }: { symbol: string; action: 'BUY' | 'SELL'; amountUsd: number }) => {
        const tradeId = `tr_${Date.now()}`;
        return { tradeId, status: 'EXECUTED' };
    },
).compensate(async ctx => {
    // Compensating rollback if subsequent steps or advisor fail!
    console.log(`Cancelling trade ${ctx.tradeId}`);
});

const executeTradeTool = defineAiTool({
    name: 'executeTrade',
    description: 'Execute a portfolio balancing trade',
    inputSchema: tradeArgs,
    jsonSchema: z.toJSONSchema(tradeArgs),
    mapInput: args => args,
    step: executeTradeStep,
});

// Output recommendation schema
const AdvisoryResultSchema = z.object({
    portfolioSummary: z.string(),
    rebalancingCompleted: z.boolean(),
    notes: z.string(),
});

export const portfolioAdvisor = aiStep('portfolioAdvisor', {
    model: { provider: 'openai', model: 'gpt-4o' },
    prompt: (ctx: { customerId: string }) => `Review and balance portfolio for customer ${ctx.customerId}.`,
    tools: [lookupPortfolioTool, executeTradeTool],
    maxToolTurns: 4,
    schema: AdvisoryResultSchema,
    jsonSchema: z.toJSONSchema(AdvisoryResultSchema),
});

export const advisoryFlow = flow(portfolioAdvisor);

export interface AiStepResult<TOutput> {
    data: TOutput; // Validated structured output or raw text string
    $aiMetrics: AiMetrics; // Telemetry and token accounting metadata
    aiMetrics: AiMetrics; // Alias for $aiMetrics
}

export interface AiMetrics {
    promptTokens: number;
    completionTokens: number;
    totalTokens: number;
    estimatedCostUsd?: number;
    latencyMs: number;
    modelUsed: string;
    providerUsed: AiProvider;
    repairAttempts: number;
    fallbackCount: number;
}