@almadar/agent 2.0.0 → 2.0.2

package/dist/orbitals/generation/orbital-generator.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Orbital Generator
+ *
+ * Provides utilities for generating FullOrbitalUnit definitions from
+ * lightweight OrbitalUnit inputs. Designed for SUBAGENT use where each
+ * orbital is generated separately for better caching.
+ *
+ * ## Subagent Caching Pattern
+ *
+ * When generating multiple orbitals in a subagent pattern:
+ * 1. Main agent decomposes request → OrbitalUnit[]
+ * 2. For each orbital, subagent calls generateFullOrbital()
+ * 3. Each subagent call uses the SAME cached system prompt blocks
+ * 4. Anthropic caches at request level → subsequent calls get 90% discount
+ *
+ * This is MORE efficient than batch generation because:
+ * - System prompt is cached and reused across subagent calls
+ * - Template guidance is cached per fingerprint
+ * - Only the orbital-specific content varies
+ *
+ * @packageDocumentation
+ */
+import type { LLMClient } from '@almadar/llm';
+import { type OrbitalUnit, type OrbitalGenerationOptions as SharedOrbitalGenerationOptions, type OrbitalGenerationResult as SharedOrbitalGenerationResult, type ParallelGenerationOptions as SharedParallelGenerationOptions, type ParallelGenerationResult as SharedParallelGenerationResult, type DecomposeOptions as SharedDecomposeOptions } from '../shared/index.js';
+export { type OrbitalUnit, type GenerationLog, type ExtractedRequirements, } from '../shared/index.js';
+export { PROVIDER_CONCURRENCY_LIMITS } from '../shared/index.js';
+/**
+ * Extended options for single orbital generation.
+ * @deprecated Use shared OrbitalGenerationOptions instead
+ */
+export interface OrbitalGenerationOptions extends SharedOrbitalGenerationOptions {
+}
+/**
+ * Extended result for single orbital generation.
+ * @deprecated Use shared OrbitalGenerationResult instead
+ */
+export interface OrbitalGenerationResult extends SharedOrbitalGenerationResult {
+}
+/**
+ * Extended options for parallel generation.
+ * @deprecated Use shared ParallelGenerationOptions instead
+ */
+export interface ParallelGenerationOptions extends SharedParallelGenerationOptions {
+}
+/**
+ * Extended result for parallel generation.
+ * @deprecated Use shared ParallelGenerationResult instead
+ */
+export interface ParallelGenerationResult extends SharedParallelGenerationResult {
+}
+/**
+ * Extended options for decomposition.
+ * @deprecated Use shared DecomposeOptions instead
+ */
+export interface DecomposeOptions extends SharedDecomposeOptions {
+}
+/**
+ * Generate a full orbital unit from a lightweight orbital input.
+ *
+ * DESIGNED FOR SUBAGENT USE: Call this once per orbital in separate
+ * subagent invocations. Caching works across calls because:
+ * - System prompt blocks are marked as cacheable
+ * - Anthropic caches at the request level
+ * - Subsequent calls with same system prompt get cache hits
+ *
+ * @example
+ * ```typescript
+ * // In subagent for each orbital:
+ * const result = await generateFullOrbital(client, orbitalUnit, { validate: true });
+ * // First call: Cache WRITE: 3500 tokens
+ * // Second call: Cache HIT: 3500 tokens (90% discount!)
+ * ```
+ */
+export declare function generateFullOrbital(client: LLMClient, orbital: OrbitalUnit, options?: OrbitalGenerationOptions): Promise<OrbitalGenerationResult>;
+/**
+ * Generate multiple orbitals in parallel with concurrency control.
+ *
+ * Uses provider-specific concurrency limits to avoid rate limiting.
+ * All orbital units are independent, so parallel execution is safe.
+ *
+ * @example
+ * ```typescript
+ * // Generate all orbitals in parallel (max 3 concurrent for Anthropic)
+ * const result = await generateFullOrbitalsParallel(client, orbitals, { validate: true });
+ * console.log(`Generated ${result.summary.successful}/${result.summary.total} orbitals`);
+ * ```
+ */
+export declare function generateFullOrbitalsParallel(client: LLMClient, orbitals: OrbitalUnit[], options?: ParallelGenerationOptions): Promise<ParallelGenerationResult>;
+/**
+ * Decompose a user request into OrbitalUnits using LLM.
+ *
+ * This is typically called by the MAIN AGENT before delegating
+ * to subagents for full orbital generation.
+ *
+ * @example
+ * ```typescript
+ * // Without requirements (existing behavior):
+ * const orbitals = await decomposeToOrbitals(client, "Build a task manager");
+ *
+ * // With requirements (from analysis phase):
+ * const orbitals = await decomposeToOrbitals(client, "Build a task manager", {
+ *   requirements: { entities: ["Task"], guards: ["only admins can delete"], ... }
+ * });
+ *
+ * // Then generate all orbitals in parallel:
+ * const result = await generateFullOrbitalsParallel(client, orbitals);
+ * ```
+ */
+export declare function decomposeToOrbitals(client: LLMClient, userRequest: string, options?: DecomposeOptions): Promise<OrbitalUnit[]>;
+/**
+ * Estimate cache savings for a set of orbitals.
+ *
+ * Use this to predict how much caching will help for a decomposition.
+ */
+export declare function estimateCacheSavings(orbitals: OrbitalUnit[]): {
+    totalOrbitals: number;
+    uniqueFingerprints: number;
+    estimatedCacheHits: number;
+    estimatedSavingsPercent: number;
+};

package/dist/orbitals/shared/constants.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Shared Constants for Orbital Generation
+ *
+ * Provider limits, defaults, and configuration constants.
+ *
+ * @packageDocumentation
+ */
+import type { LLMProvider } from '@almadar/llm';
+/**
+ * Default concurrency limits per LLM provider.
+ * These are conservative defaults to avoid rate limiting.
+ */
+export declare const PROVIDER_CONCURRENCY_LIMITS: Record<LLMProvider, number>;
+/**
+ * Default batch sizes per provider (max orbitals per LLM call).
+ */
+export declare const PROVIDER_BATCH_SIZES: Record<LLMProvider, number>;
+/**
+ * Maximum tokens for generation (across all providers).
+ */
+export declare const DEFAULT_MAX_TOKENS = 8192;
+/**
+ * Maximum tokens for batch generation (higher for multi-orbital).
+ */
+export declare const BATCH_MAX_TOKENS = 12000;
+/**
+ * Token buffer for prompt overhead.
+ */
+export declare const TOKEN_BUFFER = 1000;
+/**
+ * Maximum retries for failed generation attempts.
+ */
+export declare const MAX_RETRIES = 2;
+/**
+ * Delay between retries (ms).
+ */
+export declare const RETRY_DELAY_MS = 1000;
+/**
+ * Timeout for single orbital generation (ms).
+ */
+export declare const SINGLE_GENERATION_TIMEOUT_MS = 120000;
+/**
+ * Timeout for batch generation (ms).
+ */
+export declare const BATCH_GENERATION_TIMEOUT_MS = 300000;
+/**
+ * Default LLM provider.
+ */
+export declare const DEFAULT_PROVIDER: LLMProvider;
+/**
+ * Default model for generation.
+ */
+export declare const DEFAULT_MODEL = "claude-sonnet-4-20250514";
+/**
+ * Default model for batch generation.
+ */
+export declare const DEFAULT_BATCH_MODEL = "claude-sonnet-4-20250514";
+/**
+ * Whether to enable prompt caching by default.
+ */
+export declare const DEFAULT_CACHE_ENABLED = true;
+/**
+ * Cache TTL in milliseconds (1 hour).
+ */
+export declare const CACHE_TTL_MS: number;

package/dist/orbitals/shared/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared Utilities for Orbital Generation
+ *
+ * Common types, constants, and utilities used by both sequential
+ * and batch generation modules.
+ *
+ * @packageDocumentation
+ */
+export { type OrbitalUnit, type GenerationLog, type ExtractedRequirements, type BaseGenerationOptions, type OrbitalGenerationOptions, type ParallelGenerationOptions, type BatchGenerationOptions, type TokenUsage, type ValidationResult, type OrbitalGenerationResult, type ParallelGenerationResult, type BatchGenerationResult, type DecomposeOptions, type DecomposeResult, type OrbitalBatch, type BatchProgressEvent, } from './types.js';
+export { PROVIDER_CONCURRENCY_LIMITS, PROVIDER_BATCH_SIZES, DEFAULT_MAX_TOKENS, BATCH_MAX_TOKENS, TOKEN_BUFFER, MAX_RETRIES, RETRY_DELAY_MS, SINGLE_GENERATION_TIMEOUT_MS, BATCH_GENERATION_TIMEOUT_MS, DEFAULT_PROVIDER, DEFAULT_MODEL, DEFAULT_BATCH_MODEL, DEFAULT_CACHE_ENABLED, CACHE_TTL_MS, } from './constants.js';
+export { getEntityName, getInlineEntity, getEntityPersistence, getFieldNames, getTraitNames, createLog, createOrbitalLog, buildContextSection, buildConnectivitySection, isValidOrbital, validateOrbitals, chunkArray, groupBy, asyncMapWithConcurrency, measureTime, sleep, getErrorMessage, isRateLimitError, isTimeoutError, } from './utils.js';

package/dist/orbitals/shared/types.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Shared Types for Orbital Generation
+ *
+ * Common type definitions used by both sequential and batch generation.
+ *
+ * @packageDocumentation
+ */
+import type { OrbitalDefinition, FullOrbitalUnit } from '@almadar/core/types';
+/** OrbitalUnit in generation context is always a full OrbitalDefinition */
+export type OrbitalUnit = OrbitalDefinition;
+/**
+ * A structured log entry from the generation process.
+ * Used for debugging and observability of subagent reasoning.
+ */
+export interface GenerationLog {
+    /** Timestamp of the log entry */
+    timestamp: number;
+    /** Log level */
+    level: 'info' | 'warn' | 'error' | 'debug';
+    /** Log message */
+    message: string;
+    /** Optional structured data */
+    data?: Record<string, unknown>;
+}
+/**
+ * Extracted requirements from the analysis phase.
+ * Matches ExtractedRequirements from agents/orchestrator/shared/requirements.ts
+ */
+export interface ExtractedRequirements {
+    /** Entity names to create */
+    entities?: string[];
+    /** State names that should exist */
+    states?: string[];
+    /** Event/action names */
+    events?: string[];
+    /** Business rules (become guards) */
+    guards?: string[];
+    /** Page types needed */
+    pages?: string[];
+    /** Notifications/side-effects */
+    effects?: string[];
+    /** Raw requirement statements */
+    rawRequirements?: string[];
+}
+/**
+ * Common options for all generation modes.
+ */
+export interface BaseGenerationOptions {
+    /** Maximum tokens for generation */
+    maxTokens?: number;
+    /** Enable validation after generation */
+    validate?: boolean;
+    /** Callback for real-time log streaming */
+    onLog?: (log: GenerationLog, orbitalName?: string) => void;
+    /** Optional requirements relevant to this orbital */
+    requirements?: Partial<ExtractedRequirements>;
+}
+/**
+ * Options for single orbital generation.
+ */
+export interface OrbitalGenerationOptions extends BaseGenerationOptions {
+}
+/**
+ * Options for parallel/batch generation.
+ */
+export interface ParallelGenerationOptions extends BaseGenerationOptions {
+    /** Maximum concurrent generations (default: provider-specific) */
+    concurrency?: number;
+    /** Progress callback */
+    onProgress?: (completed: number, total: number, orbitalName: string) => void;
+}
+/**
+ * Token usage statistics.
+ */
+export interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/**
+ * Validation result for generated orbital.
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errorCount: number;
+    warningCount: number;
+}
+/**
+ * Result of generating a single orbital.
+ */
+export interface OrbitalGenerationResult {
+    /** Generated full orbital unit */
+    orbital: FullOrbitalUnit;
+    /** Fingerprint used for caching */
+    fingerprint: string;
+    /** Whether template guidance was used */
+    usedTemplate: boolean;
+    /** Token usage */
+    usage?: TokenUsage;
+    /** Validation result */
+    validation?: ValidationResult;
+    /** Structured logs from generation */
+    logs: GenerationLog[];
+}
+/**
+ * Result of parallel/batch generation.
+ */
+export interface ParallelGenerationResult {
+    /** Results for each orbital (same order as input) */
+    results: OrbitalGenerationResult[];
+    /** Total duration in milliseconds */
+    totalDurationMs: number;
+    /** Aggregate logs from all generations */
+    aggregateLogs: GenerationLog[];
+    /** Summary statistics */
+    summary: {
+        total: number;
+        successful: number;
+        failed: number;
+        totalTokens: number;
+    };
+}
+/**
+ * Result of batch generation (alias for ParallelGenerationResult).
+ */
+export type BatchGenerationResult = ParallelGenerationResult;
+/**
+ * Options for decomposing a request into orbitals.
+ */
+export interface DecomposeOptions {
+    /** Maximum tokens for generation */
+    maxTokens?: number;
+    /** Optional extracted requirements from analysis phase */
+    requirements?: Partial<ExtractedRequirements>;
+    /** Optional domain context */
+    domain?: string;
+    /** Optional design hints */
+    design?: {
+        style?: 'minimal' | 'modern' | 'playful' | 'data-driven' | 'immersive';
+    };
+    /** Explicit entity list if known */
+    entities?: string[];
+}
+/**
+ * Result of decomposition.
+ */
+export interface DecomposeResult {
+    /** Generated orbital units */
+    orbitals: OrbitalUnit[];
+    /** Extracted requirements */
+    requirements?: ExtractedRequirements;
+}
+/**
+ * Options for batch generation.
+ */
+export interface BatchGenerationOptions extends ParallelGenerationOptions {
+    /** Maximum orbitals per batch (default: 3 for Anthropic, 5 for OpenAI) */
+    batchSize?: number;
+    /** Whether to use single-call batch, parallel individual calls, or adaptive */
+    mode?: 'single-call' | 'parallel-individual' | 'adaptive';
+}
+/**
+ * A batch of orbitals to generate together.
+ */
+export interface OrbitalBatch {
+    /** Batch index */
+    index: number;
+    /** Orbitals in this batch */
+    orbitals: OrbitalUnit[];
+    /** Shared context for this batch */
+    sharedContext?: {
+        domainVocabulary?: Record<string, string>;
+        designStyle?: string;
+    };
+}
+/**
+ * Progress event for batch generation.
+ */
+export interface BatchProgressEvent {
+    type: 'batch_start' | 'orbital_complete' | 'batch_complete' | 'error';
+    batchIndex: number;
+    orbitalIndex?: number;
+    orbitalName?: string;
+    completed: number;
+    total: number;
+    error?: string;
+}

package/dist/orbitals/shared/utils.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared Utilities for Orbital Generation
+ *
+ * Common utility functions used by both sequential and batch generation.
+ *
+ * @packageDocumentation
+ */
+import type { EntityRef, Entity } from '@almadar/core/types';
+import type { GenerationLog } from './types.js';
+/**
+ * Get entity name safely from EntityRef.
+ */
+export declare function getEntityName(entity: EntityRef): string;
+/**
+ * Get inline entity for detailed access, or null for references.
+ */
+export declare function getInlineEntity(entity: EntityRef): Entity | null;
+/**
+ * Get persistence type for an entity.
+ */
+export declare function getEntityPersistence(entity: EntityRef): string;
+/**
+ * Get field names as comma-separated string.
+ */
+export declare function getFieldNames(entity: EntityRef): string;
+/**
+ * Get trait names from orbital traits array.
+ */
+export declare function getTraitNames(traits: Array<{
+    name: string;
+} | string>): string;
+/**
+ * Create a generation log entry.
+ */
+export declare function createLog(level: GenerationLog['level'], message: string, data?: Record<string, unknown>): GenerationLog;
+/**
+ * Log with orbital context.
+ */
+export declare function createOrbitalLog(level: GenerationLog['level'], orbitalName: string, message: string, data?: Record<string, unknown>): GenerationLog;
+import type { OrbitalDefinition } from '@almadar/core/types';
+/**
+ * Build context section from orbital's domainContext and design fields.
+ */
+export declare function buildContextSection(orbital: OrbitalDefinition): string;
+/**
+ * Build cross-orbital connectivity section.
+ */
+export declare function buildConnectivitySection(orbital: OrbitalDefinition): string;
+/**
+ * Check if an orbital has all required fields.
+ */
+export declare function isValidOrbital(orbital: unknown): orbital is OrbitalDefinition;
+/**
+ * Validate a batch of orbitals.
+ */
+export declare function validateOrbitals(orbitals: unknown[]): {
+    valid: OrbitalDefinition[];
+    invalid: {
+        index: number;
+        reason: string;
+    }[];
+};
+/**
+ * Chunk an array into smaller arrays.
+ */
+export declare function chunkArray<T>(array: T[], size: number): T[][];
+/**
+ * Group array items by a key function.
+ */
+export declare function groupBy<T, K>(array: T[], keyFn: (item: T) => K): Map<K, T[]>;
+/**
+ * Async map with concurrency limit.
+ */
+export declare function asyncMapWithConcurrency<T, R>(items: T[], mapper: (item: T, index: number) => Promise<R>, concurrency: number): Promise<R[]>;
+/**
+ * Measure execution time of an async function.
+ */
+export declare function measureTime<T>(fn: () => Promise<T>): Promise<{
+    result: T;
+    durationMs: number;
+}>;
+/**
+ * Sleep for a specified duration.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Get error message from unknown error.
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Check if error is a rate limit error.
+ */
+export declare function isRateLimitError(error: unknown): boolean;
+/**
+ * Check if error is a timeout error.
+ */
+export declare function isTimeoutError(error: unknown): boolean;

package/dist/orchestration/complexity-classifier.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Complexity Classifier
+ *
+ * Determines the complexity of an orbital generation request
+ * based on the number of orbitals identified during decomposition.
+ */
+export type ComplexityLevel = 'simple' | 'medium' | 'complex';
+export interface ComplexityResult {
+    level: ComplexityLevel;
+    orbitalCount: number;
+    recommendedProvider: 'qwen' | 'multi-provider';
+    reasoning: string;
+}
+/**
+ * Classify complexity based on orbital count
+ *
+ * Simple: 1 orbital
+ * Medium: 2-3 orbitals
+ * Complex: 4+ orbitals
+ */
+export declare function classifyComplexity(orbitalCount: number): ComplexityResult;
+/**
+ * Quick complexity check without full decomposition
+ * Based on keywords and request length heuristics
+ */
+export declare function estimateComplexity(prompt: string): {
+    estimatedLevel: ComplexityLevel;
+    confidence: 'high' | 'medium' | 'low';
+};
+/**
+ * Get execution strategy based on complexity
+ */
+export declare function getExecutionStrategy(complexity: ComplexityResult): {
+    type: 'single' | 'multi-provider';
+    provider: string;
+    model: string;
+    parallelization: number;
+};

package/dist/orchestration/fixing-orchestrator.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Fixing Orchestrator V2 - Enhanced with better prompts and validation
+ *
+ * Improvements:
+ * 1. Error-specific fix prompts with examples
+ * 2. Skill context for proper guidance
+ * 3. Better validation of fix results
+ * 4. More detailed error categorization
+ */
+import type { OrbitalSchema } from '@almadar/core';
+import type { ValidationIssue } from '@almadar/core/types';
+export interface FixPlan {
+    summary: {
+        totalErrors: number;
+        criticalErrors: number;
+        warningErrors: number;
+        affectedOrbitals: string[];
+    };
+    executionOrder: FixStep[];
+    parallelizationStrategy: 'single' | 'multi-provider' | 'chunked';
+}
+export interface FixStep {
+    id: string;
+    description: string;
+    orbitalIndex: number;
+    errorIndices: number[];
+    provider: string;
+    dependencies: string[];
+    errorType: 'binding' | 'schema' | 'state-machine' | 'other';
+}
+export interface FixingResult {
+    success: boolean;
+    fixedSchema: OrbitalSchema | null;
+    plan: FixPlan;
+    stepsCompleted: number;
+    stepsTotal: number;
+    remainingErrors: ValidationIssue[];
+    timing: {
+        planMs: number;
+        executeMs: number;
+        verifyMs: number;
+        totalMs: number;
+    };
+}
+export interface FixingConfig {
+    maxRetries?: number;
+    verbose?: boolean;
+    skillContent?: string;
+}
+/**
+ * Main fixing orchestrator - Enhanced Version
+ */
+export declare function orchestrateFixingV2(schema: OrbitalSchema, config?: FixingConfig): Promise<FixingResult>;

package/dist/orchestration/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Orchestration Module
+ *
+ * Complexity-based provider routing for generation and fixing workflows.
+ *
+ * ## Generation Routing
+ *
+ * ```typescript
+ * const result = await routeGeneration(prompt, skillContent, {
+ *   anthropicApiKey: process.env.ANTHROPIC_API_KEY,
+ *   deepseekApiKey: process.env.DEEPSEEK_API_KEY,
+ *   openRouterApiKey: process.env.OPEN_ROUTER_API_KEY,
+ * });
+ *
+ * // result.complexity.level: 'simple' | 'medium' | 'complex'
+ * // result.provider: routing decision
+ * // result.orbitals: generated orbital definitions
+ * ```
+ *
+ * ## Complexity Classification
+ *
+ * - **Simple** (1 orbital): Qwen 397B (fastest, cheapest)
+ * - **Medium** (2-3 orbitals): Qwen 397B (good speed/cost balance)
+ * - **Complex** (4+ orbitals): Multi-provider parallel (DeepSeek + Qwen)
+ */
+export { classifyComplexity, estimateComplexity, getExecutionStrategy, } from './complexity-classifier.js';
+export type { ComplexityLevel, ComplexityResult, } from './complexity-classifier.js';
+export { routeGeneration, quickComplexityCheck, } from './provider-router.js';
+export type { RouteConfig, GenerationResult, DecomposedUnit, } from './provider-router.js';
+export { orchestrateFixingV2 as orchestrateFixing, } from './fixing-orchestrator.js';
+export type { FixPlan, FixStep, FixingResult, FixingConfig, } from './fixing-orchestrator.js';

package/dist/orchestration/provider-router.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Provider Router
+ *
+ * Routes generation and fixing requests to the appropriate provider(s)
+ * based on complexity analysis.
+ */
+import type { OrbitalDefinition } from '@almadar/core';
+import { type ComplexityResult } from './complexity-classifier.js';
+export interface RouteConfig {
+    /** Optional: Override default verbosity */
+    verbose?: boolean;
+}
+export interface GenerationResult {
+    orbitals: OrbitalDefinition[];
+    complexity: ComplexityResult;
+    timing: {
+        decomposeMs: number;
+        generateMs: number;
+        totalMs: number;
+    };
+    provider: string;
+}
+export interface DecomposedUnit {
+    name: string;
+    entity: string;
+    traits: string[];
+}
+/**
+ * Main routing function for generation
+ *
+ * 1. Decomposes the request
+ * 2. Classifies complexity
+ * 3. Routes to appropriate provider(s)
+ * 4. Returns combined results
+ */
+export declare function routeGeneration(prompt: string, skillContent: string, config?: RouteConfig): Promise<GenerationResult>;
+/**
+ * Quick check if a request is likely complex
+ * Useful for UI feedback before full decomposition
+ */
+export declare function quickComplexityCheck(prompt: string): {
+    likelyComplex: boolean;
+    confidence: 'high' | 'medium' | 'low';
+    estimatedOrbitals: number;
+};