@toyako/hive 1.0.0

package/src/providers/OpenAIProvider.ts

@@ -0,0 +1,61 @@
+/**
+ * OpenAIProvider — OpenAI-compatible API provider.
+ * Works with OpenAI, DeepSeek, Mimo, OpenRouter, and any compatible API.
+ */
+import { ProviderAdapter, ProviderConfig, ValidationResult } from "./ProviderAdapter";
+
+export class OpenAIProvider implements ProviderAdapter {
+  name: string;
+  baseUrl: string;
+  private defaultModel: string;
+
+  constructor(name: string, baseUrl: string, defaultModel: string) {
+    this.name = name;
+    this.baseUrl = baseUrl;
+    this.defaultModel = defaultModel;
+  }
+
+  async setup(apiKey: string, baseUrl?: string): Promise<ProviderConfig> {
+    const url = baseUrl || this.baseUrl;
+    const models = await this.listModels(apiKey, url);
+    return {
+      name: this.name,
+      baseUrl: url,
+      apiKey,
+      model: models[0] || this.defaultModel,
+      models,
+    };
+  }
+
+  async validate(apiKey: string, baseUrl: string): Promise<ValidationResult> {
+    try {
+      const res = await fetch(`${baseUrl}/models`, {
+        headers: { "Authorization": `Bearer ${apiKey}` },
+        signal: AbortSignal.timeout(10000),
+      } as any);
+
+      if (res.ok) {
+        const data = await res.json() as any;
+        const models = (data.data || []).map((m: any) => m.id);
+        return { valid: true, models };
+      }
+      return { valid: false, error: `HTTP ${res.status}` };
+    } catch (err: any) {
+      return { valid: false, error: err.message };
+    }
+  }
+
+  async listModels(apiKey: string, baseUrl: string): Promise<string[]> {
+    const result = await this.validate(apiKey, baseUrl);
+    return result.models || [];
+  }
+}
+
+// Pre-configured providers
+export const PROVIDER_INSTANCES = {
+  openai: new OpenAIProvider("OpenAI", "https://api.openai.com/v1", "gpt-4"),
+  deepseek: new OpenAIProvider("DeepSeek", "https://api.deepseek.com/v1", "deepseek-chat"),
+  openrouter: new OpenAIProvider("OpenRouter", "https://openrouter.ai/api/v1", "anthropic/claude-sonnet-4"),
+  mimo: new OpenAIProvider("Mimo", "https://token-plan-sgp.xiaomimimo.com/v1", "mimo-v2.5-pro"),
+  ollama: new OpenAIProvider("Ollama", "http://localhost:11434/v1", "llama3"),
+};

package/src/providers/ProviderAdapter.ts

@@ -0,0 +1,32 @@
+/**
+ * ProviderAdapter — unified interface for all AI providers.
+ * Each provider implements setup(), validate(), listModels().
+ */
+
+export interface ProviderAdapter {
+  name: string;
+  baseUrl: string;
+
+  /** Setup the provider (save config) */
+  setup(apiKey: string, baseUrl?: string): Promise<ProviderConfig>;
+
+  /** Validate API key and connection */
+  validate(apiKey: string, baseUrl: string): Promise<ValidationResult>;
+
+  /** List available models */
+  listModels(apiKey: string, baseUrl: string): Promise<string[]>;
+}
+
+export interface ProviderConfig {
+  name: string;
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+  models: string[];
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  error?: string;
+  models?: string[];
+}

package/src/reasoning/ArchitectureCandidateGenerator.ts

@@ -0,0 +1,103 @@
+/**
+ * Architecture Candidate Generator — Architecture Reasoning Layer 3
+ * 
+ * 生成有限候选集合
+ * 
+ * Scoring MUST be deterministic formula:
+ * score = (fitToScale * 0.3) + (operationalSimplicity * 0.25) + (scalability * 0.25) + (costEfficiency * 0.2)
+ */
+
+import { Constraints } from "./ConstraintInferenceEngine";
+import { ArchitectureSpace } from "./ArchitectureSpaceGenerator";
+
+// Architecture Candidate
+export interface ArchitectureCandidate {
+  type: string;
+  score: number;
+  assumptions: string[];
+}
+
+export class ArchitectureCandidateGenerator {
+  /**
+   * 生成候选架构
+   */
+  generate(constraints: Constraints, space: ArchitectureSpace): ArchitectureCandidate[] {
+    const candidates: ArchitectureCandidate[] = [];
+
+    for (const pattern of space.allowedPatterns) {
+      for (const db of space.allowedDatabases) {
+        for (const backend of space.allowedBackends) {
+          const type = `${pattern}+${db}+${backend}`;
+          const score = this.calculateScore(pattern, db, backend, constraints);
+          const assumptions = this.getAssumptions(pattern, db, backend);
+
+          candidates.push({ type, score, assumptions });
+        }
+      }
+    }
+
+    // 按分数排序
+    return candidates.sort((a, b) => b.score - a.score);
+  }
+
+  /**
+   * 计算分数（确定性公式）
+   */
+  private calculateScore(
+    pattern: string,
+    db: string,
+    backend: string,
+    constraints: Constraints
+  ): number {
+    const fitToScale = this.getFitToScale(pattern, constraints.scale);
+    const operationalSimplicity = this.getOperationalSimplicity(pattern, db);
+    const scalability = this.getScalability(pattern, db);
+    const costEfficiency = this.getCostEfficiency(pattern, db, backend);
+
+    return (fitToScale * 0.3) + (operationalSimplicity * 0.25) + (scalability * 0.25) + (costEfficiency * 0.2);
+  }
+
+  private getFitToScale(pattern: string, scale: string): number {
+    if (pattern === "monolith" && scale === "small") return 1.0;
+    if (pattern === "modular-monolith" && scale === "medium") return 1.0;
+    if (pattern === "microservices" && scale === "large") return 1.0;
+    return 0.5;
+  }
+
+  private getOperationalSimplicity(pattern: string, db: string): number {
+    let score = 1.0;
+    if (pattern === "microservices") score -= 0.3;
+    if (db === "sqlite") score += 0.2;
+    return Math.max(0, Math.min(1, score));
+  }
+
+  private getScalability(pattern: string, db: string): number {
+    let score = 0.5;
+    if (pattern === "microservices") score += 0.3;
+    if (db === "postgres") score += 0.2;
+    return Math.min(1, score);
+  }
+
+  private getCostEfficiency(pattern: string, db: string, backend: string): number {
+    let score = 0.8;
+    if (pattern === "microservices") score -= 0.3;
+    if (db === "sqlite") score += 0.2;
+    return Math.max(0, Math.min(1, score));
+  }
+
+  private getAssumptions(pattern: string, db: string, backend: string): string[] {
+    const assumptions: string[] = [];
+    
+    if (pattern === "microservices") {
+      assumptions.push("Requires container orchestration");
+    }
+    if (db === "sqlite") {
+      assumptions.push("Single server deployment only");
+    }
+    if (backend === "nestjs") {
+      assumptions.push("TypeScript expertise required");
+    }
+
+    return assumptions;
+  }
+}

package/src/reasoning/ArchitectureSpaceGenerator.ts

@@ -0,0 +1,73 @@
+/**
+ * Architecture Space Generator — Architecture Reasoning Layer 2
+ * 
+ * 定义搜索空间，不再"生成架构"
+ */
+
+import { Constraints } from "./ConstraintInferenceEngine";
+
+// Architecture Space
+export interface ArchitectureSpace {
+  allowedPatterns: string[];
+  allowedDatabases: string[];
+  allowedBackends: string[];
+}
+
+export class ArchitectureSpaceGenerator {
+  /**
+   * 根据约束生成架构空间
+   */
+  generate(constraints: Constraints): ArchitectureSpace {
+    return {
+      allowedPatterns: this.getAllowedPatterns(constraints),
+      allowedDatabases: this.getAllowedDatabases(constraints),
+      allowedBackends: this.getAllowedBackends(constraints)
+    };
+  }
+
+  private getAllowedPatterns(constraints: Constraints): string[] {
+    const patterns: string[] = ["monolith"];
+
+    if (constraints.teamScale !== "solo") {
+      patterns.push("modular-monolith");
+    }
+
+    if (constraints.scale === "large" || constraints.teamScale === "enterprise") {
+      patterns.push("microservices");
+    }
+
+    return patterns;
+  }
+
+  private getAllowedDatabases(constraints: Constraints): string[] {
+    const dbs: string[] = [];
+
+    // SQLite 只允许小规模
+    if (constraints.dataVolume === "small" && constraints.concurrency === "low") {
+      dbs.push("sqlite");
+    }
+
+    // PostgreSQL 适用于所有场景
+    dbs.push("postgres");
+
+    // MySQL 适用于中等规模
+    if (constraints.scale !== "large") {
+      dbs.push("mysql");
+    }
+
+    // MongoDB 适用于非结构化数据
+    dbs.push("mongodb");
+
+    return dbs;
+  }
+
+  private getAllowedBackends(constraints: Constraints): string[] {
+    const backends: string[] = ["express"];
+
+    if (constraints.scale !== "small") {
+      backends.push("nestjs");
+    }
+
+    return backends;
+  }
+}

package/src/reasoning/ConstraintInferenceEngine.ts

@@ -0,0 +1,110 @@
+/**
+ * Constraint Inference Engine — Architecture Reasoning Layer 1
+ * 
+ * 从 Domain Model + User Intent + System Context 推断约束
+ * 
+ * HARD RULES:
+ * - IF dataVolume = massive → prohibit sqlite
+ * - IF concurrency = high → require stateless backend
+ * - IF consistency = strong → require transactional DB
+ * - IF teamScale = enterprise → modular architecture required
+ */
+
+// Constraints
+export interface Constraints {
+  scale: "small" | "medium" | "large";
+  concurrency: "low" | "medium" | "high";
+  dataVolume: "small" | "large" | "massive";
+  consistency: "eventual" | "strong";
+  deploymentModel: "single-server" | "cloud" | "distributed";
+  teamScale: "solo" | "team" | "enterprise";
+}
+
+export class ConstraintInferenceEngine {
+  /**
+   * 推断约束
+   */
+  infer(context: {
+    domain?: string;
+    intent?: string;
+    scale?: string;
+    users?: number;
+    teamSize?: number;
+  }): Constraints {
+    return {
+      scale: this.inferScale(context),
+      concurrency: this.inferConcurrency(context),
+      dataVolume: this.inferDataVolume(context),
+      consistency: this.inferConsistency(context),
+      deploymentModel: this.inferDeploymentModel(context),
+      teamScale: this.inferTeamScale(context)
+    };
+  }
+
+  /**
+   * 应用 HARD RULES
+   */
+  applyHardRules(constraints: Constraints): { valid: boolean; violations: string[] } {
+    const violations: string[] = [];
+
+    // IF dataVolume = massive → prohibit sqlite
+    if (constraints.dataVolume === "massive") {
+      violations.push("SQLite prohibited for massive data volume");
+    }
+
+    // IF concurrency = high → require stateless backend
+    if (constraints.concurrency === "high") {
+      // 这是要求，不是禁止
+    }
+
+    // IF consistency = strong → require transactional DB
+    if (constraints.consistency === "strong") {
+      violations.push("Transactional DB required for strong consistency");
+    }
+
+    // IF teamScale = enterprise → modular architecture required
+    if (constraints.teamScale === "enterprise") {
+      violations.push("Modular architecture required for enterprise team");
+    }
+
+    return {
+      valid: violations.length === 0,
+      violations
+    };
+  }
+
+  private inferScale(context: any): Constraints["scale"] {
+    if (context.scale === "large" || (context.users && context.users > 100000)) return "large";
+    if (context.scale === "medium" || (context.users && context.users > 10000)) return "medium";
+    return "small";
+  }
+
+  private inferConcurrency(context: any): Constraints["concurrency"] {
+    if (context.users && context.users > 100000) return "high";
+    if (context.users && context.users > 10000) return "medium";
+    return "low";
+  }
+
+  private inferDataVolume(context: any): Constraints["dataVolume"] {
+    if (context.users && context.users > 1000000) return "massive";
+    if (context.users && context.users > 100000) return "large";
+    return "small";
+  }
+
+  private inferConsistency(context: any): Constraints["consistency"] {
+    if (context.domain === "finance" || context.domain === "healthcare") return "strong";
+    return "eventual";
+  }
+
+  private inferDeploymentModel(context: any): Constraints["deploymentModel"] {
+    if (context.users && context.users > 100000) return "distributed";
+    if (context.users && context.users > 10000) return "cloud";
+    return "single-server";
+  }
+
+  private inferTeamScale(context: any): Constraints["teamScale"] {
+    if (context.teamSize && context.teamSize > 10) return "enterprise";
+    if (context.teamSize && context.teamSize > 3) return "team";
+    return "solo";
+  }
+}

package/src/reasoning/DecisionEngine.ts

@@ -0,0 +1,102 @@
+/**
+ * Decision Engine — Architecture Reasoning Layer 6
+ * 
+ * 输出必须可审计
+ */
+
+import { ArchitectureCandidate } from "./ArchitectureCandidateGenerator";
+import { TradeoffAnalysis } from "./TradeoffReasoningEngine";
+import { FailureSimulation } from "./FailureSimulationEngine";
+
+// Architecture Decision
+export interface ArchitectureDecision {
+  selected: string;
+  confidence: number;
+  reasoningChain: string[];
+  rejectedCandidates: {
+    type: string;
+    reasonRejected: string;
+  }[];
+  constraintConflicts: string[];
+}
+
+export class DecisionEngine {
+  /**
+   * 做出架构决策
+   */
+  decide(
+    candidates: ArchitectureCandidate[],
+    tradeoffs: Map<string, TradeoffAnalysis>,
+    simulations: Map<string, FailureSimulation>
+  ): ArchitectureDecision {
+    if (candidates.length === 0) {
+      throw new Error("No candidates to decide from");
+    }
+
+    // 选择得分最高的候选
+    const selected = candidates[0];
+    
+    // 计算置信度
+    const confidence = this.calculateConfidence(selected, candidates);
+
+    // 生成推理链
+    const reasoningChain = this.generateReasoningChain(selected, tradeoffs, simulations);
+
+    // 记录被拒绝的候选
+    const rejectedCandidates = candidates.slice(1).map(c => ({
+      type: c.type,
+      reasonRejected: this.getRejectionReason(c, selected)
+    }));
+
+    return {
+      selected: selected.type,
+      confidence,
+      reasoningChain,
+      rejectedCandidates,
+      constraintConflicts: []
+    };
+  }
+
+  private calculateConfidence(
+    selected: ArchitectureCandidate,
+    allCandidates: ArchitectureCandidate[]
+  ): number {
+    if (allCandidates.length === 1) return 1.0;
+
+    const secondBest = allCandidates[1];
+    const scoreDiff = selected.score - secondBest.score;
+    
+    // 分数差距越大，置信度越高
+    return Math.min(1.0, 0.5 + scoreDiff * 2);
+  }
+
+  private generateReasoningChain(
+    candidate: ArchitectureCandidate,
+    tradeoffs: Map<string, TradeoffAnalysis>,
+    simulations: Map<string, FailureSimulation>
+  ): string[] {
+    const chain: string[] = [];
+    const [pattern, db, backend] = candidate.type.split("+");
+
+    chain.push(`Selected ${pattern} architecture with ${db} and ${backend}`);
+    chain.push(`Score: ${candidate.score.toFixed(2)}`);
+
+    const tradeoff = tradeoffs.get(candidate.type);
+    if (tradeoff) {
+      chain.push(`Pros: ${tradeoff.pros.join(", ")}`);
+      chain.push(`Risks: ${tradeoff.risks.join(", ")}`);
+    }
+
+    const simulation = simulations.get(candidate.type);
+    if (simulation) {
+      chain.push(`Bottlenecks: ${simulation.bottlenecks.join(", ")}`);
+    }
+
+    return chain;
+  }
+
+  private getRejectionReason(candidate: ArchitectureCandidate, selected: ArchitectureCandidate): string {
+    const scoreDiff = selected.score - candidate.score;
+    return `Lower score (${candidate.score.toFixed(2)} vs ${selected.score.toFixed(2)}), diff: ${scoreDiff.toFixed(2)}`;
+  }
+}

package/src/reasoning/ExplainabilityLayer.ts

@@ -0,0 +1,72 @@
+/**
+ * Explainability Layer — Architecture Reasoning Layer 7
+ * 
+ * 必须输出：
+ * - WHY this architecture
+ * - WHY not others
+ * - WHAT will break first
+ * - WHEN system fails
+ */
+
+import { ArchitectureDecision } from "./DecisionEngine";
+import { TradeoffAnalysis } from "./TradeoffReasoningEngine";
+import { FailureSimulation } from "./FailureSimulationEngine";
+
+// Architecture Explanation
+export interface ArchitectureExplanation {
+  whyThis: string;
+  whyNotOthers: string[];
+  whatBreaksFirst: string;
+  whenSystemFails: string;
+}
+
+export class ExplainabilityLayer {
+  /**
+   * 生成解释
+   */
+  explain(
+    decision: ArchitectureDecision,
+    tradeoff?: TradeoffAnalysis,
+    simulation?: FailureSimulation
+  ): ArchitectureExplanation {
+    return {
+      whyThis: this.generateWhyThis(decision, tradeoff),
+      whyNotOthers: this.generateWhyNotOthers(decision),
+      whatBreaksFirst: this.generateWhatBreaksFirst(simulation),
+      whenSystemFails: this.generateWhenSystemFails(simulation)
+    };
+  }
+
+  private generateWhyThis(decision: ArchitectureDecision, tradeoff?: TradeoffAnalysis): string {
+    const reasons: string[] = [];
+    
+    reasons.push(`Selected ${decision.selected}`);
+    reasons.push(`Confidence: ${(decision.confidence * 100).toFixed(0)}%`);
+    
+    if (tradeoff) {
+      reasons.push(`Key advantages: ${tradeoff.pros.slice(0, 2).join(", ")}`);
+    }
+
+    return reasons.join(". ");
+  }
+
+  private generateWhyNotOthers(decision: ArchitectureDecision): string[] {
+    return decision.rejectedCandidates.map(c => 
+      `${c.type}: ${c.reasonRejected}`
+    );
+  }
+
+  private generateWhatBreaksFirst(simulation?: FailureSimulation): string {
+    if (!simulation || simulation.bottlenecks.length === 0) {
+      return "Unknown - no simulation data";
+    }
+    return simulation.bottlenecks[0];
+  }
+
+  private generateWhenSystemFails(simulation?: FailureSimulation): string {
+    if (!simulation || simulation.saturationPoints.length === 0) {
+      return "Unknown - no saturation data";
+    }
+    return `System saturates at: ${simulation.saturationPoints.join(", ")}`;
+  }
+}

package/src/reasoning/FailureSimulationEngine.ts

@@ -0,0 +1,102 @@
+/**
+ * Failure Simulation Engine — Architecture Reasoning Layer 5
+ * 
+ * 模拟：
+ * - DB overload
+ * - API saturation
+ * - Queue backlog
+ * - Single point of failure
+ */
+
+import { ArchitectureCandidate } from "./ArchitectureCandidateGenerator";
+
+// Failure Simulation
+export interface FailureSimulation {
+  bottlenecks: string[];
+  failureModes: string[];
+  saturationPoints: string[];
+  breakingConditions: string[];
+}
+
+export class FailureSimulationEngine {
+  /**
+   * 模拟故障
+   */
+  simulate(candidate: ArchitectureCandidate): FailureSimulation {
+    const [pattern, db, backend] = candidate.type.split("+");
+
+    return {
+      bottlenecks: this.getBottlenecks(pattern, db, backend),
+      failureModes: this.getFailureModes(pattern, db, backend),
+      saturationPoints: this.getSaturationPoints(pattern, db, backend),
+      breakingConditions: this.getBreakingConditions(pattern, db, backend)
+    };
+  }
+
+  private getBottlenecks(pattern: string, db: string, backend: string): string[] {
+    const bottlenecks: string[] = [];
+
+    // DB overload
+    if (db === "sqlite") {
+      bottlenecks.push("SQLite write lock under concurrent load");
+    }
+    if (db === "postgres") {
+      bottlenecks.push("Connection pool exhaustion at high concurrency");
+    }
+
+    // API saturation
+    if (backend === "express") {
+      bottlenecks.push("Single-threaded event loop saturation");
+    }
+
+    // Queue backlog
+    if (pattern === "microservices") {
+      bottlenecks.push("Message queue backlog under burst load");
+    }
+
+    return bottlenecks;
+  }
+
+  private getFailureModes(pattern: string, db: string, backend: string): string[] {
+    const modes: string[] = [];
+
+    modes.push("Database connection timeout");
+    modes.push("API response timeout");
+    
+    if (pattern === "microservices") {
+      modes.push("Service discovery failure");
+      modes.push("Circuit breaker open");
+    }
+
+    return modes;
+  }
+
+  private getSaturationPoints(pattern: string, db: string, backend: string): string[] {
+    const points: string[] = [];
+
+    if (db === "sqlite") {
+      points.push("~100 concurrent writes");
+    }
+    if (db === "postgres") {
+      points.push("~10,000 concurrent connections");
+    }
+    if (backend === "express") {
+      points.push("~10,000 requests/second per instance");
+    }
+
+    return points;
+  }
+
+  private getBreakingConditions(pattern: string, db: string, backend: string): string[] {
+    const conditions: string[] = [];
+
+    if (db === "sqlite") {
+      conditions.push("Multiple writers will cause SQLITE_BUSY");
+    }
+    if (pattern === "monolith") {
+      conditions.push("Single server memory limit");
+    }
+
+    return conditions;
+  }
+}