Agent System

interface RequirementsAgent {
  input: {
    prd: string;           // PRD.md content
  };

  output: {
    constraints: {
      electrical: ElectricalConstraints;
      mechanical: MechanicalConstraints;
      environmental: EnvironmentalConstraints;
      cost: CostConstraints;
    };
    assumptions: Assumption[];
  };

  tools: [
    "Neo4jAdapter",
    "MinIOAdapter"
  ];
}

interface ArchitectureAgent {
  input: {
    constraints: Constraints;
  };

  output: {
    architecture: {
      microcontroller: Component;
      sensors: Component[];
      communication: Component[];
      power: PowerArchitecture;
      blockDiagram: MermaidDiagram;
    };
  };

  tools: [
    "DigiKeyAdapter",
    "MouserAdapter",
    "NexarAdapter",
    "Neo4jAdapter",
    "MinIOAdapter"
  ];
}

interface ComponentOrModule {
  type: 'discrete_component' | 'dev_board' | 'system_on_module' | 'breakout_module';
}

interface DevelopmentBoard extends ComponentOrModule {
  type: 'dev_board';
  board_name: string;           // "STM32 Nucleo-F446RE"
  mcu_specs: MCUSpecification;
  pricing: {
    unit_cost: number;          // $24.99
    availability: 'high' | 'medium' | 'low';
    suppliers: string[];        // ["DigiKey", "Mouser", "Arduino.cc"]
  };
  use_case: 'POC' | 'EVT' | 'Low-volume-production';
  transition_path?: string;     // "Migrate to custom STM32F405 for EVT"
  io_capabilities: {
    gpio_count: number;
    adc_channels: number;
    uart_ports: number;
    i2c_buses: number;
    spi_buses: number;
  };
}

interface SystemOnModule extends ComponentOrModule {
  type: 'system_on_module';
  module_name: string;          // "Raspberry Pi Compute Module 4"
  processor_specs: ProcessorSpecification;
  pricing: {
    unit_cost: number;          // $35-$90 (depending on RAM/storage)
    moq: number;                // Minimum order quantity
    lead_time_weeks: number;
  };
  carrier_board_required: boolean;
  use_case: 'EVT' | 'DVT' | 'Production';
  volume_recommendation: {
    min_viable_volume: number;  // 100 units
    max_recommended_volume: number; // 10,000 units
  };
}

interface BreakoutModule extends ComponentOrModule {
  type: 'breakout_module';
  module_name: string;          // "Adafruit BME280"
  sensor_specs: SensorSpecification;
  pricing: {
    unit_cost: number;          // $14.95
    bulk_discount?: number;     // 10+ units: $12.95
  };
  interface: 'I2C' | 'SPI' | 'UART' | 'Analog';
  use_case: 'POC' | 'EVT';
  transition_path?: string;     // "Use discrete BME280 for DVT ($4.20 @ 100)"
}

interface ModuleRecommendations {
  strategy: 'modules_only' | 'hybrid' | 'custom_only';
  phase_specific: {
    POC?: PhaseRecommendation;
    EVT?: PhaseRecommendation;
    DVT?: PhaseRecommendation;
  };
  tradeoff_summary: TradeoffSummary;
  transition_plan?: TransitionPlan;
}

interface TradeoffSummary {
  time_advantage: {
    modules_timeline: string;   // "1-2 weeks"
    custom_timeline: string;    // "6-8 weeks"
    delta_weeks: number;        // 5-6 weeks saved
  };
  cost_breakeven: {
    module_unit_cost: number;
    custom_unit_cost: number;
    breakeven_quantity: number;
  };
  form_factor_impact: {
    module_size: string;        // "70mm x 30mm"
    custom_size: string;        // "40mm x 25mm"
    size_ratio: number;         // 2.1x larger
  };
}

interface TransitionPlan {
  current_phase: 'POC' | 'EVT' | 'DVT';
  next_phase: 'EVT' | 'DVT' | 'Production';
  recommended_changes: string[];
  cost_impact: string;
  timeline_impact: string;
}

interface PowerBudgetAgent {
  input: {
    architecture: Architecture;
    usage_profile: UsageProfile;
  };

  output: {
    budget: {
      components: PowerBreakdown[];
      total_active: number;
      total_sleep: number;
      battery_life: BatteryLifeEstimate;
    };
  };

  tools: [
    "Neo4jAdapter",
    "MinIOAdapter"
  ];
}

interface BOMAgent {
  input: {
    architecture: Architecture;
    schematic: SchematicPlan;
  };

  output: {
    bom: BOMEntry[];
    alternates: AlternateComponent[];
    costing: CostAnalysis;
  };

  tools: [
    "DigiKeyAdapter",
    "MouserAdapter",
    "NexarAdapter",
    "Neo4jAdapter",
    "MinIOAdapter"
  ];
}

interface SystemsAgent {
  input: {
    requirements: Constraints;
    architecture: Architecture;
  };

  output: {
    traceability: {
      matrix: TraceabilityEntry[];
      coverage: number; // percentage of requirements traced
    };
    interfaces: InterfaceDefinition[];
    integration: IntegrationPlan;
    verification: VerificationPlan;
  };

  tools: [
    "Neo4jAdapter",
    "MinIOAdapter"
  ];
}

interface TraceabilityEntry {
  requirement_id: string;
  requirement_text: string;
  implementation: {
    file: string;
    component: string;
    function?: string;
  };
  verification: {
    test_id: string;
    test_procedure: string;
  };
  status: 'traced' | 'partial' | 'not_traced';
}

interface FirmwareAgent {
  input: {
    architecture: Architecture;
    pinout: PinoutDefinition;
    requirements: FirmwareRequirements;
  };

  output: {
    firmware: {
      hal: HardwareAbstractionLayer;
      drivers: Driver[];
      rtos_config: RTOSConfig;
      application: ApplicationScaffold;
      build_system: BuildConfig;
    };
    completeness: number; // percentage ready to compile
  };

  tools: [
    "GCCToolchainAdapter",
    "CMakeAdapter",
    "KiCadAdapter",
    "Neo4jAdapter",
    "MinIOAdapter"
  ];
}

interface Driver {
  peripheral: string; // "I2C", "SPI", "UART", "PWM"
  files: string[]; // ["i2c_driver.c", "i2c_driver.h"]
  api: Function[];
  dependencies: string[];
}

interface SimulationAgent {
  input: {
    schematic: SchematicNetlist;
    mechanical: CADModel;
    requirements: SimulationRequirements;
  };

  output: {
    spice: SPICEResults;
    fea: FEAResults;
    cfd: CFDResults;
    reports: SimulationReport[];
    passed: boolean;
  };

  tools: [
    "NGSpiceAdapter",
    "KiCadAdapter",
    "Neo4jAdapter",
    "MinIOAdapter"
  ];
}

interface SPICEResults {
  dc_analysis: DCOperatingPoint;
  ac_analysis: FrequencyResponse;
  transient: TransientResponse;
  issues: Issue[];
}

interface ManufacturingAgent {
  input: {
    pcb_design: PCBFiles;
    bom: BillOfMaterials;
    quantity: number;
  };

  output: {
    dfm_report: DFMValidation;
    assembly_instructions: AssemblyDoc;
    work_instructions: WorkInstruction[];
    vendor_quotes: VendorQuote[];
    issues: ManufacturingIssue[];
  };

  tools: [
    "KiCadAdapter",
    "Neo4jAdapter",
    "MinIOAdapter"
  ];
}

interface DFMValidation {
  checks: DFMCheck[];
  score: number; // 0-100
  manufacturability: 'excellent' | 'good' | 'fair' | 'poor';
  estimated_yield: number; // percentage
}

interface TestEngineeringAgent {
  input: {
    requirements: Requirements;
    architecture: Architecture;
    risk_analysis: FMEA;
  };

  output: {
    test_plan: TestPlan;
    test_cases: TestCase[];
    fmea: FMEAAnalysis;
    coverage: TestCoverage;
  };

  tools: [
    "KiCadAdapter",
    "GitHubActionsAdapter",
    "Neo4jAdapter",
    "MinIOAdapter"
  ];
}

interface TestCase {
  id: string;
  name: string;
  objective: string;
  requirements_traced: string[];
  procedure: TestStep[];
  acceptance_criteria: AcceptanceCriteria;
  equipment_needed: Equipment[];
}

interface SupplyChainAgent {
  input: {
    bom: BillOfMaterials;
    quantity: number;
    target_date: Date;
  };

  output: {
    bom_with_risk: BOMWithRisk;
    alternates: AlternateComponents;
    eol_warnings: EOLWarning[];
    sourcing_strategy: SourcingStrategy;
    lead_time_analysis: LeadTimeAnalysis;
  };

  tools: [
    "DigiKeyAdapter",
    "MouserAdapter",
    "NexarAdapter",
    "Neo4jAdapter",
    "MinIOAdapter"
  ];
}

interface BOMWithRisk {
  entries: BOMEntry[];
  overall_risk: 'low' | 'medium' | 'high' | 'critical';
  risk_score: number; // 0-100
  availability_score: number; // 0-100
}

interface EOLWarning {
  component: string;
  mpn: string;
  status: 'active' | 'nrnd' | 'obsolete';
  last_time_buy?: Date;
  recommended_action: string;
  alternates: Component[];
}

import { Agent, AgentConfig, ExecutionContext } from '@metaforge/core';

export class CustomAgent implements Agent {
  name = 'custom-agent';
  version = '1.0.0';
  description = 'Your agent description';

  private llm: LLMProvider;
  private tools: ToolRegistry;

  async initialize(config: AgentConfig): Promise<void> {
    this.llm = config.llmProvider;
    this.tools = config.toolRegistry;
  }

  async execute(context: ExecutionContext): Promise<AgentResult> {
    // 1. Load input
    const input = await this.loadInput(context);

    // 2. Validate input
    const validation = this.validateInput(input);
    if (!validation.valid) {
      throw new Error(`Invalid input: ${validation.errors}`);
    }

    // 3. Build prompt
    const prompt = this.buildPrompt(input);

    // 4. Call LLM
    const response = await this.llm.complete(prompt, {
      tools: this.getTools(),
      temperature: 0.3,
      maxTokens: 4000
    });

    // 5. Parse response
    const output = this.parseResponse(response);

    // 6. Validate output
    const outputValidation = this.validateOutput(output);
    if (!outputValidation.valid) {
      throw new Error(`Invalid output: ${outputValidation.errors}`);
    }

    // 7. Return artifacts
    return {
      artifacts: output.artifacts,
      metadata: output.metadata,
      traces: this.getTraces()
    };
  }

  validateInput(input: any): ValidationResult {
    // Implement input validation
  }

  validateOutput(output: any): ValidationResult {
    // Implement output validation
  }

  private buildPrompt(input: any): string {
    return `
You are a specialist agent for ${this.description}.

Input:
${JSON.stringify(input, null, 2)}

Task:
[Your specific task description]

Output Format:
[Expected JSON schema]
    `.trim();
  }
}

export class CustomAgent implements Agent {
  registerTools(registry: ToolRegistry): void {
    registry.register({
      name: 'read_datasheet',
      description: 'Read component datasheet',
      parameters: {
        component: { type: 'string', required: true }
      },
      execute: async (params) => {
        // Tool implementation
      }
    });
  }

  private getTools(): Tool[] {
    return this.tools.getByNames([
      'read_datasheet',
      'search_components'
    ]);
  }
}

import { z } from 'zod';

const InputSchema = z.object({
  constraints: z.object({
    voltage: z.number().positive(),
    current: z.number().positive()
  })
});

const OutputSchema = z.object({
  components: z.array(z.object({
    part_number: z.string(),
    manufacturer: z.string(),
    price: z.number()
  }))
});

export class CustomAgent implements Agent {
  validateInput(input: any): ValidationResult {
    try {
      InputSchema.parse(input);
      return { valid: true };
    } catch (error) {
      return {
        valid: false,
        errors: error.errors
      };
    }
  }

  validateOutput(output: any): ValidationResult {
    try {
      OutputSchema.parse(output);
      return { valid: true };
    } catch (error) {
      return {
        valid: false,
        errors: error.errors
      };
    }
  }
}

import { describe, it, expect } from 'vitest';
import { CustomAgent } from './custom-agent';

describe('CustomAgent', () => {
  it('validates input correctly', () => {
    const agent = new CustomAgent();
    const result = agent.validateInput({
      constraints: { voltage: 3.3, current: 0.5 }
    });

    expect(result.valid).toBe(true);
  });

  it('generates valid output', async () => {
    const agent = new CustomAgent();
    await agent.initialize(mockConfig);

    const result = await agent.execute(mockContext);

    expect(result.artifacts).toBeDefined();
    expect(agent.validateOutput(result).valid).toBe(true);
  });
});

describe('CustomAgent Integration', () => {
  it('integrates with gateway', async () => {
    const gateway = await startGateway();
    const result = await gateway.runSkill('custom-skill');

    expect(result.status).toBe('completed');
    expect(result.artifacts).toHaveLength(2);
  });
});

// ❌ Bad: Vague prompt
const prompt = "Analyze this design";

// ✅ Good: Specific prompt
const prompt = `
Analyze the power consumption of this hardware design.

Given:
- Components: ${components}
- Usage profile: ${usage}

Calculate:
1. Active current (mA)
2. Sleep current (µA)
3. Battery life (days) for ${batteryCapacity}mAh battery

Output as JSON with schema:
{
  "active_ma": number,
  "sleep_ua": number,
  "battery_life_days": number
}
`;

// ✅ Use JSON schema validation
const response = await llm.complete(prompt, {
  response_format: { type: "json_object" },
  schema: OutputSchema
});

async execute(context: ExecutionContext): Promise<AgentResult> {
  try {
    return await this.executeInternal(context);
  } catch (error) {
    if (error instanceof ValidationError) {
      // Retry with feedback
      return await this.retryWithFeedback(context, error);
    }

    if (error instanceof ToolError) {
      // Log and fail gracefully
      this.logger.error('Tool execution failed', error);
      throw new AgentError('Tool failure', { cause: error });
    }

    throw error;
  }
}

class CustomAgent implements Agent {
  private traces: Trace[] = [];

  private trace(action: string, data: any): void {
    this.traces.push({
      timestamp: new Date(),
      agent: this.name,
      action,
      data,
      level: 'info'
    });
  }

  async execute(context: ExecutionContext): Promise<AgentResult> {
    this.trace('execution_started', { input: context.input });

    const result = await this.executeInternal(context);

    this.trace('execution_completed', {
      artifacts: result.artifacts.map(a => a.path)
    });

    return { ...result, traces: this.traces };
  }
}