@shahmarasy/prodo 0.1.4 → 0.1.5

package/src/agents/agent-registry.ts

@@ -0,0 +1,93 @@
+import type { AgentPlugin } from "./base";
+import { UserError } from "../core/errors";
+import type { LLMProvider } from "../core/types";
+import { MockAgent } from "./mock";
+import { OpenAIAgent } from "./openai";
+import { AnthropicAgent } from "./anthropic";
+import { GoogleAgent } from "./google";
+
+const AGENT_ALIASES: Record<string, string> = {
+  mock: "mock",
+  openai: "openai",
+  anthropic: "anthropic",
+  claude: "anthropic",
+  google: "google",
+  gemini: "google"
+};
+
+export class AgentRegistry {
+  private agents = new Map<string, AgentPlugin>();
+
+  register(agent: AgentPlugin): void {
+    this.agents.set(agent.name, agent);
+  }
+
+  list(): AgentPlugin[] {
+    return Array.from(this.agents.values());
+  }
+
+  get(name: string): AgentPlugin | undefined {
+    const normalized = AGENT_ALIASES[name.toLowerCase().trim()] ?? name.toLowerCase().trim();
+    return this.agents.get(normalized);
+  }
+
+  async resolve(name?: string): Promise<AgentPlugin> {
+    const agentName = this.resolveAgentName(name);
+    const agent = this.get(agentName);
+
+    if (!agent) {
+      const available = this.list().map((a) => a.name).join(", ");
+      throw new UserError(
+        `Unknown agent: "${agentName}". Available agents: ${available}`
+      );
+    }
+
+    return agent;
+  }
+
+  private resolveAgentName(override?: string): string {
+    if (override) return override;
+
+    const fromEnv = process.env.PRODO_AGENT;
+    if (fromEnv) return fromEnv;
+
+    const fromLegacy = process.env.PRODO_LLM_PROVIDER;
+    if (fromLegacy) return fromLegacy;
+
+    const isTest =
+      process.env.NODE_ENV === "test" ||
+      process.env.PRODO_TEST === "1";
+    if (isTest) return "mock";
+
+    return "mock";
+  }
+
+  toProvider(agent: AgentPlugin): LLMProvider {
+    return {
+      generate: (prompt, inputContext, schemaHint) =>
+        agent.generate(prompt, inputContext, schemaHint)
+    };
+  }
+}
+
+let globalRegistry: AgentRegistry | null = null;
+
+function createDefaultRegistry(): AgentRegistry {
+  const registry = new AgentRegistry();
+  registry.register(new MockAgent());
+  registry.register(new OpenAIAgent());
+  registry.register(new AnthropicAgent());
+  registry.register(new GoogleAgent());
+  return registry;
+}
+
+export function getGlobalRegistry(): AgentRegistry {
+  if (!globalRegistry) {
+    globalRegistry = createDefaultRegistry();
+  }
+  return globalRegistry;
+}
+
+export function resetGlobalRegistry(): void {
+  globalRegistry = null;
+}

package/src/agents/anthropic/index.ts

@@ -0,0 +1,86 @@
+import { BaseAgent, type AgentConfig } from "../base";
+import { buildSystemPrompt, buildUserMessage } from "../system-prompts";
+import { UserError } from "../../core/errors";
+import type { GenerateResult, ProviderSchemaHint } from "../../core/types";
+
+const dynamicImport = new Function("specifier", "return import(specifier)") as (
+  specifier: string
+) => Promise<unknown>;
+
+type ContentBlock = { type: string; text?: string };
+
+export class AnthropicAgent extends BaseAgent {
+  readonly name = "anthropic";
+  readonly displayName = "Anthropic Claude";
+  readonly sdkRequired = "@anthropic-ai/sdk";
+
+  getConfig(): AgentConfig {
+    return {
+      name: this.name,
+      displayName: this.displayName,
+      sdkRequired: this.sdkRequired,
+      envVars: ["ANTHROPIC_API_KEY"],
+      defaultModel: "claude-sonnet-4-20250514"
+    };
+  }
+
+  async generate(
+    prompt: string,
+    inputContext: Record<string, unknown>,
+    schemaHint: ProviderSchemaHint
+  ): Promise<GenerateResult> {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+      throw new UserError("ANTHROPIC_API_KEY is not set. Set it to use the Anthropic agent.");
+    }
+
+    const model = process.env.PRODO_ANTHROPIC_MODEL ?? "claude-sonnet-4-20250514";
+
+    const outputLanguage =
+      typeof inputContext.outputLanguage === "string" && inputContext.outputLanguage.trim()
+        ? inputContext.outputLanguage.trim()
+        : "en";
+
+    const system = buildSystemPrompt(schemaHint, outputLanguage);
+    const user = buildUserMessage(prompt, inputContext);
+
+    let AnthropicConstructor: new (opts: { apiKey: string }) => {
+      messages: {
+        create: (params: Record<string, unknown>) => Promise<{
+          content: ContentBlock[];
+        }>;
+      };
+    };
+
+    try {
+      const mod = (await dynamicImport("@anthropic-ai/sdk")) as {
+        default: typeof AnthropicConstructor;
+      };
+      AnthropicConstructor = mod.default;
+    } catch {
+      throw new UserError(
+        "Anthropic SDK is not installed. Run: npm install @anthropic-ai/sdk"
+      );
+    }
+
+    const client = new AnthropicConstructor({ apiKey });
+
+    const response = await client.messages.create({
+      model,
+      max_tokens: 8192,
+      system,
+      messages: [{ role: "user", content: user }]
+    });
+
+    const textBlock = response.content.find(
+      (block: ContentBlock) => block.type === "text"
+    );
+    const content = textBlock?.text?.trim() ?? "";
+
+    if (!content) {
+      throw new UserError("Anthropic agent returned an empty response.");
+    }
+
+    return { body: content };
+  }
+}

package/src/agents/anthropic/manifest.json

@@ -0,0 +1,7 @@
+{
+  "name": "anthropic",
+  "displayName": "Anthropic Claude",
+  "sdkRequired": "@anthropic-ai/sdk",
+  "envVars": ["ANTHROPIC_API_KEY"],
+  "defaultModel": "claude-sonnet-4-20250514"
+}

package/src/agents/base.ts

@@ -0,0 +1,77 @@
+import type { GenerateResult, ProviderSchemaHint } from "../core/types";
+
+export type AgentConfig = {
+  name: string;
+  displayName: string;
+  sdkRequired: string | null;
+  envVars: string[];
+  defaultModel?: string;
+};
+
+export interface AgentPlugin {
+  readonly name: string;
+  readonly displayName: string;
+  readonly sdkRequired: string | null;
+
+  generate(
+    prompt: string,
+    inputContext: Record<string, unknown>,
+    schemaHint: ProviderSchemaHint
+  ): Promise<GenerateResult>;
+
+  isAvailable(): Promise<boolean>;
+  getConfig(): AgentConfig;
+}
+
+export abstract class BaseAgent implements AgentPlugin {
+  abstract readonly name: string;
+  abstract readonly displayName: string;
+  abstract readonly sdkRequired: string | null;
+
+  abstract generate(
+    prompt: string,
+    inputContext: Record<string, unknown>,
+    schemaHint: ProviderSchemaHint
+  ): Promise<GenerateResult>;
+
+  abstract getConfig(): AgentConfig;
+
+  async isAvailable(): Promise<boolean> {
+    const config = this.getConfig();
+
+    if (config.sdkRequired) {
+      try {
+        await import(config.sdkRequired);
+      } catch {
+        return false;
+      }
+    }
+
+    for (const envVar of config.envVars) {
+      if (!process.env[envVar]) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  availabilityHint(): string {
+    const config = this.getConfig();
+    const hints: string[] = [];
+
+    if (config.sdkRequired) {
+      hints.push(`SDK required: npm install ${config.sdkRequired}`);
+    }
+
+    for (const envVar of config.envVars) {
+      if (!process.env[envVar]) {
+        hints.push(`Set environment variable: ${envVar}`);
+      }
+    }
+
+    return hints.length > 0
+      ? `Agent "${config.displayName}" is not available.\n  ${hints.join("\n  ")}`
+      : `Agent "${config.displayName}" is available.`;
+  }
+}

package/src/agents/google/index.ts

@@ -0,0 +1,79 @@
+import { BaseAgent, type AgentConfig } from "../base";
+import { buildSystemPrompt, buildUserMessage } from "../system-prompts";
+import { UserError } from "../../core/errors";
+import type { GenerateResult, ProviderSchemaHint } from "../../core/types";
+
+const dynamicImport = new Function("specifier", "return import(specifier)") as (
+  specifier: string
+) => Promise<unknown>;
+
+export class GoogleAgent extends BaseAgent {
+  readonly name = "google";
+  readonly displayName = "Google Gemini";
+  readonly sdkRequired = "@google/generative-ai";
+
+  getConfig(): AgentConfig {
+    return {
+      name: this.name,
+      displayName: this.displayName,
+      sdkRequired: this.sdkRequired,
+      envVars: ["GOOGLE_API_KEY"],
+      defaultModel: "gemini-2.0-flash"
+    };
+  }
+
+  async generate(
+    prompt: string,
+    inputContext: Record<string, unknown>,
+    schemaHint: ProviderSchemaHint
+  ): Promise<GenerateResult> {
+    const apiKey = process.env.GOOGLE_API_KEY;
+    if (!apiKey) {
+      throw new UserError("GOOGLE_API_KEY is not set. Set it to use the Google Gemini agent.");
+    }
+
+    const model = process.env.PRODO_GOOGLE_MODEL ?? "gemini-2.0-flash";
+
+    const outputLanguage =
+      typeof inputContext.outputLanguage === "string" && inputContext.outputLanguage.trim()
+        ? inputContext.outputLanguage.trim()
+        : "en";
+
+    const system = buildSystemPrompt(schemaHint, outputLanguage);
+    const user = buildUserMessage(prompt, inputContext);
+
+    let GoogleGenerativeAI: new (apiKey: string) => {
+      getGenerativeModel: (config: { model: string; systemInstruction: string }) => {
+        generateContent: (content: string) => Promise<{
+          response: { text: () => string };
+        }>;
+      };
+    };
+
+    try {
+      const mod = (await dynamicImport("@google/generative-ai")) as {
+        GoogleGenerativeAI: typeof GoogleGenerativeAI;
+      };
+      GoogleGenerativeAI = mod.GoogleGenerativeAI;
+    } catch {
+      throw new UserError(
+        "Google Generative AI SDK is not installed. Run: npm install @google/generative-ai"
+      );
+    }
+
+    const client = new GoogleGenerativeAI(apiKey);
+    const generativeModel = client.getGenerativeModel({
+      model,
+      systemInstruction: system
+    });
+
+    const result = await generativeModel.generateContent(user);
+    const content = result.response.text().trim();
+
+    if (!content) {
+      throw new UserError("Google Gemini agent returned an empty response.");
+    }
+
+    return { body: content };
+  }
+}

package/src/agents/google/manifest.json

@@ -0,0 +1,7 @@
+{
+  "name": "google",
+  "displayName": "Google Gemini",
+  "sdkRequired": "@google/generative-ai",
+  "envVars": ["GOOGLE_API_KEY"],
+  "defaultModel": "gemini-2.0-flash"
+}

package/src/agents/mock/index.ts

@@ -0,0 +1,32 @@
+import { BaseAgent, type AgentConfig } from "../base";
+import { MockProvider } from "../../providers/mock-provider";
+import type { GenerateResult, ProviderSchemaHint } from "../../core/types";
+
+export class MockAgent extends BaseAgent {
+  readonly name = "mock";
+  readonly displayName = "Mock (Testing)";
+  readonly sdkRequired = null;
+
+  private readonly provider = new MockProvider();
+
+  async generate(
+    prompt: string,
+    inputContext: Record<string, unknown>,
+    schemaHint: ProviderSchemaHint
+  ): Promise<GenerateResult> {
+    return this.provider.generate(prompt, inputContext, schemaHint);
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return true;
+  }
+
+  getConfig(): AgentConfig {
+    return {
+      name: this.name,
+      displayName: this.displayName,
+      sdkRequired: null,
+      envVars: []
+    };
+  }
+}

package/src/agents/mock/manifest.json

@@ -0,0 +1,7 @@
+{
+  "name": "mock",
+  "displayName": "Mock (Testing)",
+  "sdkRequired": null,
+  "envVars": [],
+  "defaultModel": null
+}

package/src/agents/openai/index.ts

@@ -0,0 +1,83 @@
+import { BaseAgent, type AgentConfig } from "../base";
+import { buildSystemPrompt, buildUserMessage } from "../system-prompts";
+import { UserError } from "../../core/errors";
+import type { GenerateResult, ProviderSchemaHint } from "../../core/types";
+
+const dynamicImport = new Function("specifier", "return import(specifier)") as (
+  specifier: string
+) => Promise<unknown>;
+
+export class OpenAIAgent extends BaseAgent {
+  readonly name = "openai";
+  readonly displayName = "OpenAI";
+  readonly sdkRequired = "openai";
+
+  getConfig(): AgentConfig {
+    return {
+      name: this.name,
+      displayName: this.displayName,
+      sdkRequired: this.sdkRequired,
+      envVars: ["OPENAI_API_KEY"],
+      defaultModel: "gpt-4o-mini"
+    };
+  }
+
+  async generate(
+    prompt: string,
+    inputContext: Record<string, unknown>,
+    schemaHint: ProviderSchemaHint
+  ): Promise<GenerateResult> {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      throw new UserError("OPENAI_API_KEY is not set. Set it to use the OpenAI agent.");
+    }
+
+    const model = process.env.PRODO_OPENAI_MODEL ?? "gpt-4o-mini";
+    const baseURL = process.env.PRODO_OPENAI_BASE_URL ?? undefined;
+
+    const outputLanguage =
+      typeof inputContext.outputLanguage === "string" && inputContext.outputLanguage.trim()
+        ? inputContext.outputLanguage.trim()
+        : "en";
+
+    const system = buildSystemPrompt(schemaHint, outputLanguage);
+    const user = buildUserMessage(prompt, inputContext);
+
+    let OpenAIConstructor: new (opts: { apiKey: string; baseURL?: string }) => {
+      chat: {
+        completions: {
+          create: (params: Record<string, unknown>) => Promise<{
+            choices: Array<{ message?: { content?: string } }>;
+          }>;
+        };
+      };
+    };
+
+    try {
+      const mod = (await dynamicImport("openai")) as { default: typeof OpenAIConstructor };
+      OpenAIConstructor = mod.default;
+    } catch {
+      throw new UserError(
+        "OpenAI SDK is not installed. Run: npm install openai"
+      );
+    }
+
+    const client = new OpenAIConstructor({ apiKey, baseURL });
+
+    const response = await client.chat.completions.create({
+      model,
+      messages: [
+        { role: "system", content: system },
+        { role: "user", content: user }
+      ],
+      temperature: 0.2
+    });
+
+    const content = response.choices[0]?.message?.content?.trim();
+    if (!content) {
+      throw new UserError("OpenAI agent returned an empty response.");
+    }
+
+    return { body: content };
+  }
+}

package/src/agents/openai/manifest.json

@@ -0,0 +1,7 @@
+{
+  "name": "openai",
+  "displayName": "OpenAI",
+  "sdkRequired": "openai",
+  "envVars": ["OPENAI_API_KEY"],
+  "defaultModel": "gpt-4o-mini"
+}

package/src/agents/system-prompts.ts

@@ -0,0 +1,35 @@
+import type { ProviderSchemaHint } from "../core/types";
+
+export function buildSystemPrompt(schemaHint: ProviderSchemaHint, outputLanguage: string): string {
+  const mode = schemaHint.artifactType;
+
+  if (mode === "normalize") {
+    return `You normalize messy human product briefs into strict JSON.
+Return valid JSON only, no markdown. Include confidence scores (0..1) for critical fields.
+Preserve source language and Unicode characters exactly; never transliterate Turkish letters to ASCII.`;
+  }
+
+  if (mode === "semantic_consistency") {
+    return `You detect semantic inconsistencies between paired artifacts.
+Return valid JSON only: { "issues": [{level, code, check, contract_id, file, message, suggestion}] }.`;
+  }
+
+  if (mode === "contract_relevance") {
+    return `You verify whether tagged content actually matches the referenced contract text.
+Return valid JSON only: { "relevant": boolean, "score": number, "reason": string }.`;
+  }
+
+  return `You are a product-document generator.
+Return only Markdown body content.
+Headings required:
+${schemaHint.requiredHeadings.join("\n")}
+Required contract tags:
+${schemaHint.requiredContracts.join(", ")}
+Use tags like [G1], [F2], [C1] where relevant.
+Output language: ${outputLanguage}
+Do not translate required headings.`;
+}
+
+export function buildUserMessage(prompt: string, inputContext: Record<string, unknown>): string {
+  return `${prompt}\n\nContext JSON:\n${JSON.stringify(inputContext, null, 2)}`;
+}