@agirails/sdk 2.5.3 → 2.5.4

package/src/level1/index.ts

@@ -1,10 +0,0 @@
-/**
- * Standard API - Agent-based interface
- *
- * @packageDocumentation
- */
-
-export { Agent, AgentConfig, AgentStatus, AgentStats, AgentBalance, ServiceConfig } from './Agent';
-export * from './types';
-export * from './pricing/PricingStrategy';
-export { calculatePrice, DEFAULT_PRICING_STRATEGY } from './pricing/PriceCalculator';

package/src/level1/pricing/PriceCalculator.ts

@@ -1,255 +0,0 @@
-/**
- * PriceCalculator - Calculate prices based on cost + margin model
- *
- * Implements the pricing logic for AGIRAILS agents to automatically
- * calculate service prices and decide whether to accept jobs.
- *
- * @packageDocumentation
- */
-
-import { PricingStrategy, PriceCalculation } from './PricingStrategy';
-import { Job } from '../types/Job';
-
-/**
- * Calculate price for a job based on pricing strategy
- *
- * This function calculates the total cost (base + per-unit), applies the
- * desired profit margin, enforces min/max bounds, and determines whether
- * to accept, counter-offer, or reject the job.
- *
- * @param strategy - Pricing strategy configuration
- * @param job - Job to calculate price for
- * @returns Price calculation result with decision
- *
- * @example
- * ```typescript
- * const strategy: PricingStrategy = {
- *   cost: {
- *     base: 0.50,
- *     perUnit: { unit: 'word', rate: 0.005 }
- *   },
- *   margin: 0.40, // 40% profit margin
- *   minimum: 0.05,
- *   maximum: 10000
- * };
- *
- * const job: Job = {
- *   id: '0x1234',
- *   service: 'translation',
- *   input: { text: 'Hello world' }, // 2 words
- *   budget: 10,
- *   deadline: new Date(),
- *   requester: '0xRequester',
- *   metadata: {}
- * };
- *
- * const calc = calculatePrice(strategy, job);
- * // calc.cost = 0.50 + (2 * 0.005) = 0.51
- * // calc.price = 0.51 / (1 - 0.40) = 0.85
- * // calc.profit = 0.85 - 0.51 = 0.34
- * // calc.marginPercent = 0.34 / 0.85 = 0.40 (40%)
- * // calc.decision = 'accept' (budget $10 >= price $0.85)
- * ```
- */
-export function calculatePrice(strategy: PricingStrategy, job: Job): PriceCalculation {
-  // Calculate base cost
-  const baseCost = strategy.cost.base ?? 0;
-
-  // Calculate per-unit cost
-  let unitCost = 0;
-  let units: number | undefined;
-  if (strategy.cost.perUnit) {
-    units = estimateUnits(job, strategy.cost.perUnit.unit);
-    unitCost = units * strategy.cost.perUnit.rate;
-  }
-
-  // Calculate API cost (future enhancement, not in MVP)
-  let apiCost: number | undefined;
-  if (strategy.cost.api) {
-    apiCost = estimateApiCost(strategy.cost.api, job);
-    // Add API cost to total cost
-  }
-
-  // Total cost = base + per-unit + api
-  const totalCost = baseCost + unitCost + (apiCost ?? 0);
-
-  // Apply margin: price = cost / (1 - margin)
-  // Example: cost=$10, margin=40% → price = $10 / 0.6 = $16.67
-  const margin = Math.max(0, Math.min(1, strategy.margin)); // Clamp to [0, 1]
-  let price = totalCost / (1 - margin);
-
-  // Enforce min/max bounds
-  const minimum = strategy.minimum ?? 0.05; // ACTP protocol minimum
-  const maximum = strategy.maximum ?? 10000;
-  price = Math.max(minimum, Math.min(maximum, price));
-
-  // Calculate actual profit and margin
-  const profit = price - totalCost;
-  const marginPercent = price > 0 ? profit / price : 0;
-
-  // Decide whether to accept the job based on budget
-  let decision: 'accept' | 'counter-offer' | 'reject';
-  let reason: string;
-
-  if (job.budget >= price) {
-    // Budget meets or exceeds our price - accept immediately
-    decision = 'accept';
-    reason = `Budget $${job.budget.toFixed(2)} >= price $${price.toFixed(2)}`;
-  } else if (job.budget >= totalCost) {
-    // Budget is below price but above cost (reduced profit)
-    // Use behavior configuration to decide
-    const belowPriceBehavior = strategy.behavior?.belowPrice ?? 'counter-offer';
-    decision = belowPriceBehavior;
-    reason = `Budget $${job.budget.toFixed(2)} below price $${price.toFixed(2)} but above cost $${totalCost.toFixed(2)}`;
-  } else {
-    // Budget is below cost (would lose money)
-    // Use behavior configuration to decide
-    const belowCostBehavior = strategy.behavior?.belowCost ?? 'reject';
-    decision = belowCostBehavior;
-    reason = `Budget $${job.budget.toFixed(2)} below cost $${totalCost.toFixed(2)} (would lose money)`;
-  }
-
-  return {
-    cost: totalCost,
-    price,
-    profit,
-    marginPercent,
-    decision,
-    reason,
-    breakdown: {
-      baseCost,
-      unitCost,
-      units,
-      apiCost,
-    },
-  };
-}
-
-/**
- * Estimate number of units in job input
- *
- * Supports different unit types (word, token, etc.) and extracts
- * the relevant data from the job input.
- *
- * @param job - Job to estimate units for
- * @param unit - Unit type (word, token, image, etc.)
- * @returns Estimated number of units
- *
- * @internal
- */
-function estimateUnits(job: Job, unit: string): number {
-  const input = job.input;
-
-  switch (unit.toLowerCase()) {
-    case 'word':
-      // Count words in text field
-      if (typeof input?.text === 'string') {
-        return input.text.split(/\s+/).filter((word: string) => word.length > 0).length;
-      }
-      // Fallback: count words in JSON string
-      return JSON.stringify(input).split(/\s+/).length;
-
-    case 'token':
-      // Rough estimate: 1 token ≈ 4 characters
-      if (typeof input?.text === 'string') {
-        return Math.ceil(input.text.length / 4);
-      }
-      return Math.ceil(JSON.stringify(input).length / 4);
-
-    case 'character':
-    case 'char':
-      // Count characters
-      if (typeof input?.text === 'string') {
-        return input.text.length;
-      }
-      return JSON.stringify(input).length;
-
-    case 'image':
-    case 'img':
-      // Count number of images
-      if (Array.isArray(input?.images)) {
-        return input.images.length;
-      }
-      if (input?.image || input?.imageUrl) {
-        return 1;
-      }
-      return 1; // Default to 1 image
-
-    case 'minute':
-    case 'min':
-      // Duration in minutes
-      if (typeof input?.duration === 'number') {
-        return input.duration;
-      }
-      if (typeof input?.durationMinutes === 'number') {
-        return input.durationMinutes;
-      }
-      return 1; // Default to 1 minute
-
-    case 'request':
-    case 'job':
-      // Flat per-request pricing
-      return 1;
-
-    default:
-      // Unknown unit type - default to 1
-      return 1;
-  }
-}
-
-/**
- * Estimate API cost for a job
- *
- * MVP: Returns 0 for all APIs (placeholder for future implementation)
- *
- * Future implementation will include pricing for:
- * - openai:gpt-4-turbo
- * - openai:gpt-3.5-turbo
- * - anthropic:claude-3-sonnet
- * - anthropic:claude-3-haiku
- *
- * @param api - API identifier (e.g., 'openai:gpt-4-turbo')
- * @param job - Job to estimate cost for
- * @returns Estimated API cost in USDC
- *
- * @internal
- */
-function estimateApiCost(_api: string, _job: Job): number {
-  // MVP: Returns 0 (API costs tracked externally by agent)
-  // V2: Integrate with OpenAI/Anthropic pricing APIs
-
-  // Example V2 implementation:
-  // const [provider, model] = api.split(':');
-  // if (provider === 'openai') {
-  //   const inputTokens = estimateUnits(job, 'token');
-  //   const pricing = {
-  //     'gpt-4-turbo': { input: 0.01 / 1000, output: 0.03 / 1000 },
-  //     'gpt-3.5-turbo': { input: 0.0005 / 1000, output: 0.0015 / 1000 }
-  //   };
-  //   return inputTokens * pricing[model].input * 2; // Assume 2x for output
-  // }
-
-  return 0;
-}
-
-/**
- * Default pricing strategy
- *
- * Provides a sensible default for services that don't specify pricing.
- * - Base cost: $0.05 (ACTP minimum)
- * - Margin: 40% (healthy profit margin)
- * - Behavior: Counter-offer when below price, reject when below cost
- */
-export const DEFAULT_PRICING_STRATEGY: PricingStrategy = {
-  cost: {
-    base: 0.05, // ACTP protocol minimum
-  },
-  margin: 0.4, // 40% profit margin
-  minimum: 0.05,
-  maximum: 10000,
-  behavior: {
-    belowPrice: 'counter-offer',
-    belowCost: 'reject',
-    maxNegotiationRounds: 3,
-  },
-};

package/src/level1/pricing/PricingStrategy.ts

@@ -1,198 +0,0 @@
-/**
- * PricingStrategy - Cost + Margin pricing model
- *
- * Allows agents to define their costs and desired profit margin.
- * SDK automatically calculates prices and decides whether to accept jobs.
- *
- * @packageDocumentation
- */
-
-/**
- * Cost configuration for a service
- */
-export interface ServiceCost {
-  /**
-   * Fixed base cost per job (USDC)
-   *
-   * @example
-   * base: 0.50 // $0.50 per job regardless of input size
-   */
-  base?: number;
-
-  /**
-   * Per-unit cost
-   *
-   * Allows pricing based on input size (words, tokens, images, etc.)
-   *
-   * @example
-   * ```typescript
-   * perUnit: {
-   *   unit: 'word',
-   *   rate: 0.005  // $0.005 per word
-   * }
-   * // For 1000-word translation: cost = 0.50 (base) + 1000 * 0.005 = $5.50
-   * ```
-   */
-  perUnit?: {
-    /**
-     * Unit type (word, token, image, minute, request, etc.)
-     */
-    unit: string;
-
-    /**
-     * Cost per unit (USDC)
-     */
-    rate: number;
-  };
-
-  /**
-   * API cost auto-calculation
-   *
-   * Automatically calculate costs based on known API pricing.
-   * SDK knows the costs for common APIs (OpenAI, Anthropic, etc.)
-   *
-   * @example
-   * ```typescript
-   * api: 'openai:gpt-4-turbo'
-   * // SDK automatically calculates cost based on input tokens
-   * ```
-   *
-   * Supported APIs (MVP):
-   * - 'openai:gpt-4-turbo'
-   * - 'openai:gpt-3.5-turbo'
-   * - 'anthropic:claude-3-sonnet'
-   * - 'anthropic:claude-3-haiku'
-   */
-  api?: string;
-}
-
-/**
- * Pricing behavior when job budget is below calculated price
- */
-export type BelowPriceBehavior = 'reject' | 'counter-offer';
-
-/**
- * Pricing behavior when job budget is below cost (would lose money)
- */
-export type BelowCostBehavior = 'reject' | 'counter-offer';
-
-/**
- * Pricing strategy configuration
- */
-export interface PricingStrategy {
-  /**
-   * Cost configuration
-   */
-  cost: ServiceCost;
-
-  /**
-   * Desired profit margin (0.0 - 1.0)
-   *
-   * This is the percentage of profit you want to make on top of your costs.
-   *
-   * @example
-   * margin: 0.40 // 40% profit margin
-   *
-   * // If cost is $10, price will be:
-   * // price = cost / (1 - margin) = $10 / 0.6 = $16.67
-   * // profit = $16.67 - $10 = $6.67 (40% of $16.67)
-   */
-  margin: number;
-
-  /**
-   * Minimum price in USDC
-   *
-   * Even if calculated price is lower, never accept less than this.
-   *
-   * @default 0.05 (ACTP protocol minimum)
-   */
-  minimum?: number;
-
-  /**
-   * Maximum price in USDC
-   *
-   * Never charge more than this, even if calculated price is higher.
-   *
-   * @default 10000
-   */
-  maximum?: number;
-
-  /**
-   * Pricing behavior configuration
-   */
-  behavior?: {
-    /**
-     * What to do when job budget is below calculated price but above cost
-     *
-     * - 'reject': Reject the job immediately
-     * - 'counter-offer': Respond with QUOTED state with your price
-     *
-     * @default 'counter-offer'
-     */
-    belowPrice?: BelowPriceBehavior;
-
-    /**
-     * What to do when job budget is below cost (would lose money)
-     *
-     * - 'reject': Reject the job immediately (recommended)
-     * - 'counter-offer': Respond with QUOTED state with your price
-     *
-     * @default 'reject'
-     */
-    belowCost?: BelowCostBehavior;
-
-    /**
-     * Maximum negotiation rounds
-     *
-     * How many times to counter-offer before giving up.
-     *
-     * @default 3
-     */
-    maxNegotiationRounds?: number;
-  };
-}
-
-/**
- * Price calculation result
- */
-export interface PriceCalculation {
-  /**
-   * Total cost (USDC)
-   */
-  cost: number;
-
-  /**
-   * Calculated price with margin (USDC)
-   */
-  price: number;
-
-  /**
-   * Profit amount (USDC)
-   */
-  profit: number;
-
-  /**
-   * Profit margin percentage (0.0 - 1.0)
-   */
-  marginPercent: number;
-
-  /**
-   * Decision: should we accept the job at the offered budget?
-   */
-  decision: 'accept' | 'counter-offer' | 'reject';
-
-  /**
-   * Reason for decision
-   */
-  reason: string;
-
-  /**
-   * Breakdown of cost calculation (for debugging)
-   */
-  breakdown: {
-    baseCost: number;
-    unitCost: number;
-    units?: number;
-    apiCost?: number;
-  };
-}

package/src/level1/types/Job.ts

@@ -1,179 +0,0 @@
-/**
- * Job - Represents a work request from requester to provider
- *
- * This is the core data structure passed to service handlers
- * in the Basic and Standard APIs.
- *
- * @packageDocumentation
- */
-
-/**
- * Job interface - work request data
- *
- * @example
- * ```typescript
- * const job: Job = {
- *   id: '0x1234...abcd',
- *   service: 'translation',
- *   input: { text: 'Hello', from: 'en', to: 'de' },
- *   budget: 10,
- *   deadline: new Date('2025-12-14T12:00:00Z'),
- *   requester: '0xRequester...',
- *   metadata: { priority: 'high' }
- * }
- * ```
- */
-export interface Job {
-  /**
-   * Unique job identifier (transaction ID from ACTP protocol)
-   */
-  id: string;
-
-  /**
-   * Service type being requested (e.g., 'translation', 'echo', 'image-gen')
-   */
-  service: string;
-
-  /**
-   * Input data for the service (service-specific)
-   *
-   * This is the data the requester wants processed.
-   * Structure depends on the service type.
-   */
-  input: any;
-
-  /**
-   * Budget in USDC (decimal format, e.g., 10 = $10.00)
-   *
-   * This is the maximum amount the requester is willing to pay.
-   */
-  budget: number;
-
-  /**
-   * Deadline by which work must be completed
-   */
-  deadline: Date;
-
-  /**
-   * Ethereum address of the requester
-   */
-  requester: string;
-
-  /**
-   * Additional metadata (optional, service-specific)
-   */
-  metadata: Record<string, any>;
-}
-
-/**
- * Job handler function type
- *
- * This is the function signature providers must implement.
- *
- * @param job - The job to process
- * @param context - Job execution context
- * @returns Promise resolving to job result (service-specific)
- *
- * @example
- * ```typescript
- * const handler: JobHandler = async (job, ctx) => {
- *   ctx.progress(50, 'Processing...');
- *   const result = await doWork(job.input);
- *   ctx.progress(100, 'Done!');
- *   return result;
- * };
- * ```
- */
-export type JobHandler = (job: Job, context: JobContext) => Promise<any>;
-
-/**
- * JobContext - Execution context passed to job handlers
- *
- * Provides utilities for progress reporting, logging, state management,
- * and cancellation handling.
- */
-export interface JobContext {
-  /**
-   * Reference to the Agent instance processing this job
-   */
-  agent: any; // Will be typed as Agent once implemented
-
-  /**
-   * Report job progress
-   *
-   * @param percent - Progress percentage (0-100)
-   * @param message - Optional progress message
-   *
-   * @example
-   * ```typescript
-   * ctx.progress(25, 'Downloaded input file');
-   * ctx.progress(50, 'Processing data');
-   * ctx.progress(100, 'Complete!');
-   * ```
-   */
-  progress(percent: number, message?: string): void;
-
-  /**
-   * Logging utilities
-   */
-  log: {
-    debug(message: string, meta?: any): void;
-    info(message: string, meta?: any): void;
-    warn(message: string, meta?: any): void;
-    error(message: string, meta?: any): void;
-  };
-
-  /**
-   * Job-scoped state storage
-   *
-   * Allows handlers to store intermediate state that persists
-   * across async operations (e.g., for resumable jobs).
-   *
-   * @example
-   * ```typescript
-   * // Store checkpoint
-   * ctx.state.set('lastProcessedIndex', 42);
-   *
-   * // Retrieve checkpoint
-   * const lastIndex = ctx.state.get<number>('lastProcessedIndex') || 0;
-   * ```
-   */
-  state: {
-    get<T>(key: string): T | undefined;
-    set<T>(key: string, value: T): void;
-  };
-
-  /**
-   * Whether the job has been cancelled
-   *
-   * Handlers should check this periodically for long-running jobs
-   * and exit gracefully if true.
-   *
-   * @example
-   * ```typescript
-   * for (let i = 0; i < items.length; i++) {
-   *   if (ctx.cancelled) {
-   *     throw new Error('Job cancelled by requester');
-   *   }
-   *   await processItem(items[i]);
-   * }
-   * ```
-   */
-  cancelled: boolean;
-
-  /**
-   * Register cancellation handler
-   *
-   * Called when the job is cancelled, allowing cleanup.
-   *
-   * @example
-   * ```typescript
-   * const stream = openFileStream();
-   * ctx.onCancel(() => {
-   *   stream.close();
-   *   console.log('Cleaned up resources');
-   * });
-   * ```
-   */
-  onCancel(handler: () => void): void;
-}