@agentlang/agentmanager 0.0.3

package/libs/agentcraft/src/services/design-generator.service.ts

@@ -0,0 +1,672 @@
+import { Injectable, Inject, Optional, Logger } from '@nestjs/common';
+import { CRAFT_LLM_PROVIDER } from '../constants';
+import { CraftLlmProvider } from '../interfaces/llm-provider.interface';
+import type { ToolDefinition } from '../types/llm.types';
+import {
+  DecompositionResult,
+  RequirementsResult,
+  DesignResult,
+  AppSpec,
+  EntitySpec,
+  RelationshipSpec,
+  WorkflowSpec,
+  EventSpec,
+  AgentSpec,
+  FeatureAnnotation,
+} from '../types/architect.types';
+import { kebabToPascalCase, pascalToKebabCase } from '../utils/text-utils';
+import { SEMANTICS_GUIDE } from '../prompts/semantics-guide';
+
+const FEATURE_ANNOTATION_SCHEMA = {
+  type: 'object',
+  required: ['feature', 'rationale'],
+  additionalProperties: false,
+  properties: {
+    feature: { type: 'string' },
+    rationale: {
+      type: 'string',
+      description: 'Why this feature is needed for this construct',
+    },
+  },
+};
+
+const ENTITY_SCHEMA = {
+  type: 'object',
+  required: ['name', 'description'],
+  additionalProperties: false,
+  properties: {
+    name: { type: 'string', description: 'PascalCase entity name' },
+    description: { type: 'string' },
+    features: {
+      type: 'array',
+      items: {
+        ...FEATURE_ANNOTATION_SCHEMA,
+        properties: {
+          ...FEATURE_ANNOTATION_SCHEMA.properties,
+          feature: {
+            type: 'string',
+            enum: [
+              'audit',
+              'fullTextSearch',
+              'rbac',
+              'triggers',
+              'compositeUnique',
+              'computedFields',
+              'actions',
+            ],
+          },
+        },
+      },
+    },
+  },
+};
+
+const RELATIONSHIP_SCHEMA = {
+  type: 'object',
+  required: ['name', 'between', 'type', 'kind', 'rationale'],
+  additionalProperties: false,
+  properties: {
+    name: { type: 'string' },
+    between: {
+      type: 'array',
+      items: { type: 'string' },
+      minItems: 2,
+      maxItems: 2,
+    },
+    type: { type: 'string', enum: ['one_one', 'one_many', 'many_many'] },
+    kind: { type: 'string', enum: ['contains', 'between'] },
+    rationale: { type: 'string' },
+    roleAliases: {
+      type: 'array',
+      items: { type: 'string' },
+      minItems: 2,
+      maxItems: 2,
+    },
+    hasSchema: { type: 'boolean' },
+    hasSchemaRationale: { type: 'string' },
+  },
+};
+
+const EVENT_SCHEMA = {
+  type: 'object',
+  required: ['name', 'public', 'description'],
+  additionalProperties: false,
+  properties: {
+    name: { type: 'string' },
+    public: { type: 'boolean' },
+    description: { type: 'string' },
+  },
+};
+
+const TRIGGER_ON_SCHEMA = {
+  type: 'object',
+  required: ['timing', 'operation', 'entity'],
+  additionalProperties: false,
+  properties: {
+    timing: { type: 'string', enum: ['before', 'after'] },
+    operation: { type: 'string', enum: ['create', 'update', 'delete'] },
+    entity: { type: 'string' },
+  },
+};
+
+const WORKFLOW_SCHEMA = {
+  type: 'object',
+  required: ['name', 'description', 'dataTouched'],
+  additionalProperties: false,
+  properties: {
+    name: { type: 'string' },
+    description: { type: 'string' },
+    dataTouched: { type: 'array', items: { type: 'string' } },
+    triggerOn: { ...TRIGGER_ON_SCHEMA },
+    withRole: { type: 'string' },
+  },
+};
+
+const AGENT_SCHEMA = {
+  type: 'object',
+  required: ['name', 'description', 'tools', 'goal'],
+  additionalProperties: false,
+  properties: {
+    name: { type: 'string' },
+    description: { type: 'string' },
+    goal: { type: 'string' },
+    tools: { type: 'array', items: { type: 'string' } },
+    capabilities: {
+      type: 'array',
+      items: {
+        ...FEATURE_ANNOTATION_SCHEMA,
+        properties: {
+          ...FEATURE_ANNOTATION_SCHEMA.properties,
+          feature: {
+            type: 'string',
+            enum: [
+              'responseSchema',
+              'documents',
+              'stateless',
+              'validation',
+              'scratch',
+              'compact',
+            ],
+          },
+        },
+      },
+    },
+  },
+};
+
+const APP_SPEC_SCHEMA = {
+  type: 'object',
+  required: [
+    'appName',
+    'moduleName',
+    'entities',
+    'relationships',
+    'events',
+    'workflows',
+    'agents',
+  ],
+  additionalProperties: false,
+  properties: {
+    appName: { type: 'string' },
+    moduleName: { type: 'string' },
+    entities: { type: 'array', items: ENTITY_SCHEMA },
+    relationships: { type: 'array', items: RELATIONSHIP_SCHEMA },
+    events: { type: 'array', items: EVENT_SCHEMA },
+    workflows: { type: 'array', items: WORKFLOW_SCHEMA },
+    agents: { type: 'array', items: AGENT_SCHEMA },
+  },
+};
+
+@Injectable()
+export class DesignGeneratorService {
+  private readonly logger = new Logger(DesignGeneratorService.name);
+
+  private readonly designTool: ToolDefinition = {
+    name: 'produce_design',
+    description:
+      'Produce the structured design allocating entities, relationships, events, workflows, and agents to exactly one app each.',
+    inputSchema: {
+      type: 'object',
+      required: ['baseline', 'subApps'],
+      additionalProperties: false,
+      properties: {
+        baseline: APP_SPEC_SCHEMA,
+        subApps: { type: 'array', items: APP_SPEC_SCHEMA },
+      },
+    },
+  };
+
+  constructor(
+    @Inject(CRAFT_LLM_PROVIDER)
+    @Optional()
+    private readonly llm: CraftLlmProvider | null,
+  ) {}
+
+  async generateDesign(
+    kbContent: string,
+    projectName: string,
+    decomposition: DecompositionResult,
+    requirements?: RequirementsResult,
+  ): Promise<DesignResult> {
+    if (!this.llm) throw new Error('LLM provider not configured');
+
+    this.logger.log(`Generating design for "${projectName}"`);
+    const baselineAppName = requirements?.baseline.appName;
+    const systemPrompt = this.buildDesignPrompt(
+      projectName,
+      decomposition,
+      baselineAppName,
+    );
+
+    const userParts = [`## Knowledge Base\n\n${kbContent}`];
+    if (requirements) {
+      userParts.push('', '## Detailed Requirements Per App', '');
+      userParts.push(`### Baseline: ${requirements.baseline.appName}`);
+      userParts.push(requirements.baseline.requirements);
+      for (const sub of requirements.subApps) {
+        userParts.push('', `### Sub-app: ${sub.appName}`);
+        userParts.push(sub.requirements);
+      }
+    }
+
+    const response = await this.llm.chat({
+      system: systemPrompt,
+      messages: [{ role: 'user', content: userParts.join('\n') }],
+      maxTokens: 64000,
+      tools: [this.designTool],
+      toolChoice: { type: 'tool', name: 'produce_design' },
+      cacheControl: true,
+    });
+
+    this.logger.log(
+      `LLM response received (toolCalls: ${response.toolCalls?.length ?? 0}, truncated: ${response.truncated ?? false})`,
+    );
+
+    if (response.truncated) {
+      throw new Error(
+        `Design generation was truncated (output tokens: ${response.usage?.outputTokens ?? '?'}).`,
+      );
+    }
+
+    const toolCall = response.toolCalls?.[0];
+    if (toolCall) {
+      this.logger.log('Parsing design from tool call');
+      return this.parseToolCallInput(
+        toolCall.input,
+        projectName,
+        decomposition,
+        baselineAppName,
+      );
+    }
+
+    // Fallback: parse text
+    const text = response.content
+      .filter((b) => b.type === 'text')
+      .map((b) => b.text)
+      .join('');
+    return this.parseDesignResponse(
+      text,
+      projectName,
+      decomposition,
+      baselineAppName,
+    );
+  }
+
+  private buildDesignPrompt(
+    projectName: string,
+    decomposition: DecompositionResult,
+    baselineAppName?: string,
+  ): string {
+    const baseAppName = baselineAppName ?? kebabToPascalCase(projectName);
+    const baseModuleName = `${baseAppName}.core`;
+
+    const subAppEntries = decomposition.subApps
+      .map((s) => `  - "${s.name}" (module: ${s.name}.core): ${s.description}`)
+      .join('\n');
+
+    return `You are an application architect. You have already decomposed an application into a baseline data model and sub-apps. Now you must produce a detailed design — a structured allocation of every entity, relationship, event, workflow, and agent to exactly one app, with design rationale.
+
+${SEMANTICS_GUIDE}
+
+## Decomposition
+
+**Baseline**: ${decomposition.baselineDescription}
+
+**Sub-apps**:
+${subAppEntries}
+
+## Rules
+
+1. Every entity, relationship, event, workflow, and agent must belong to exactly ONE app — no duplication across apps.
+2. The **baseline app** ("${baseAppName}", module \`${baseModuleName}\`) contains ONLY shared entities and relationships. No events, no workflows, no agents.
+3. Each **sub-app** contains its own LOCAL entities, relationships, events, workflows, and agents.
+4. If a sub-app needs a baseline entity, it references it — it does NOT get a copy.
+5. Entity names must be PascalCase.
+6. Event names must be PascalCase.
+7. Agent names must be PascalCase ending in "Agent".
+8. Relationship names must be PascalCase.
+9. For event-driven workflows, the workflow name must match the event name exactly. For lifecycle trigger workflows, provide \`triggerOn\`.
+10. For each relationship, choose \`contains\` or \`between\` and explain WHY.
+11. For each workflow, describe what it does and which entities it reads/writes.
+12. For each agent, provide a goal explaining its high-level objective.
+13. For agent tools, list entity names, relationship names, and event names the agent needs.
+14. For each entity, include \`features\` if it needs entity-level capabilities.
+15. For self-referencing relationships, provide \`roleAliases\`.
+16. If a workflow requires role-based access control, provide \`withRole\`.
+17. For each agent, include \`capabilities\` if it needs special features.
+
+Call the \`produce_design\` tool with the complete design.`;
+  }
+
+  private parseToolCallInput(
+    input: unknown,
+    projectName: string,
+    decomposition: DecompositionResult,
+    baselineAppName?: string,
+  ): DesignResult {
+    if (!input || typeof input !== 'object') {
+      throw new Error('Design tool call input is not an object.');
+    }
+
+    const obj = input as Record<string, unknown>;
+    const baseAppName = baselineAppName ?? kebabToPascalCase(projectName);
+    const baseline = this.parseAppSpec(
+      obj.baseline,
+      baseAppName,
+      `${baseAppName}.core`,
+    );
+
+    const subAppsRaw = obj.subApps ?? obj.sub_apps ?? obj.subapps;
+    if (!Array.isArray(subAppsRaw)) {
+      throw new Error(
+        `Design tool call must include a subApps array. Got keys: ${Object.keys(obj).join(', ')}`,
+      );
+    }
+
+    const subApps: AppSpec[] = subAppsRaw.map((s: unknown, i: number) => {
+      const fallbackName = decomposition.subApps[i]?.name ?? `SubApp${i + 1}`;
+      return this.parseAppSpec(s, fallbackName, `${fallbackName}.core`);
+    });
+
+    return { baseline, subApps };
+  }
+
+  parseDesignResponse(
+    response: string,
+    projectName: string,
+    decomposition: DecompositionResult,
+    baselineAppName?: string,
+  ): DesignResult {
+    let json = response.trim();
+    json = json.replace(/^```(?:json)?\s*\n?/i, '').replace(/\n?```\s*$/i, '');
+    const braceIdx = json.indexOf('{');
+    if (braceIdx > 0) json = json.slice(braceIdx);
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(json);
+    } catch {
+      throw new Error(
+        `Failed to parse design JSON from LLM response.\nResponse starts with: ${response.slice(0, 200)}`,
+      );
+    }
+
+    return this.parseToolCallInput(
+      parsed,
+      projectName,
+      decomposition,
+      baselineAppName,
+    );
+  }
+
+  private parseAppSpec(
+    raw: unknown,
+    fallbackName: string,
+    fallbackModule: string,
+  ): AppSpec {
+    if (!raw || typeof raw !== 'object') {
+      throw new Error(
+        `Design app spec for "${fallbackName}" is not an object.`,
+      );
+    }
+
+    const obj = raw as Record<string, unknown>;
+    const appName =
+      typeof obj.appName === 'string' ? obj.appName : fallbackName;
+    const dirName = pascalToKebabCase(appName);
+    const moduleName =
+      typeof obj.moduleName === 'string' ? obj.moduleName : fallbackModule;
+
+    const entities: EntitySpec[] = Array.isArray(obj.entities)
+      ? obj.entities
+          .map((e: unknown) => {
+            const eo = e as Record<string, unknown>;
+            const features: FeatureAnnotation[] = Array.isArray(eo.features)
+              ? eo.features
+                  .map((f: unknown) => {
+                    const fo = f as Record<string, unknown>;
+                    return {
+                      feature: typeof fo.feature === 'string' ? fo.feature : '',
+                      rationale:
+                        typeof fo.rationale === 'string' ? fo.rationale : '',
+                    };
+                  })
+                  .filter((f) => f.feature)
+              : [];
+            return {
+              name: typeof eo.name === 'string' ? eo.name : '',
+              description:
+                typeof eo.description === 'string' ? eo.description : '',
+              features,
+            };
+          })
+          .filter((e) => e.name)
+      : [];
+
+    const relationships: RelationshipSpec[] = Array.isArray(obj.relationships)
+      ? obj.relationships
+          .map((r: unknown) => {
+            const ro = r as Record<string, unknown>;
+            const between: [string, string] =
+              Array.isArray(ro.between) && ro.between.length >= 2
+                ? [String(ro.between[0]), String(ro.between[1])]
+                : ['', ''];
+            const type =
+              typeof ro.type === 'string' &&
+              ['one_one', 'one_many', 'many_many'].includes(ro.type)
+                ? (ro.type as RelationshipSpec['type'])
+                : 'one_many';
+            const kind =
+              typeof ro.kind === 'string' &&
+              ['contains', 'between'].includes(ro.kind)
+                ? (ro.kind as 'contains' | 'between')
+                : 'between';
+            const spec: RelationshipSpec = {
+              name: typeof ro.name === 'string' ? ro.name : '',
+              between,
+              type,
+              kind,
+              rationale: typeof ro.rationale === 'string' ? ro.rationale : '',
+            };
+            if (Array.isArray(ro.roleAliases) && ro.roleAliases.length >= 2) {
+              spec.roleAliases = [
+                String(ro.roleAliases[0]),
+                String(ro.roleAliases[1]),
+              ];
+            }
+            if (ro.hasSchema === true) {
+              spec.hasSchema = true;
+              if (typeof ro.hasSchemaRationale === 'string') {
+                spec.hasSchemaRationale = ro.hasSchemaRationale;
+              }
+            }
+            return spec;
+          })
+          .filter((r) => r.name)
+      : [];
+
+    const events: EventSpec[] = Array.isArray(obj.events)
+      ? obj.events
+          .map((e: unknown) => {
+            const eo = e as Record<string, unknown>;
+            return {
+              name: typeof eo.name === 'string' ? eo.name : '',
+              public: eo.public === true,
+              description:
+                typeof eo.description === 'string' ? eo.description : '',
+            };
+          })
+          .filter((e) => e.name)
+      : [];
+
+    const workflows: WorkflowSpec[] = Array.isArray(obj.workflows)
+      ? obj.workflows
+          .map((w: unknown) => {
+            const wo = w as Record<string, unknown>;
+            const spec: WorkflowSpec = {
+              name: typeof wo.name === 'string' ? wo.name : '',
+              description:
+                typeof wo.description === 'string' ? wo.description : '',
+              dataTouched: Array.isArray(wo.dataTouched)
+                ? wo.dataTouched.filter(
+                    (d): d is string => typeof d === 'string',
+                  )
+                : [],
+            };
+            if (wo.triggerOn && typeof wo.triggerOn === 'object') {
+              const t = wo.triggerOn as Record<string, unknown>;
+              const timing = String(t.timing ?? '');
+              const operation = String(t.operation ?? '');
+              const entity = String(t.entity ?? '');
+              if (
+                ['before', 'after'].includes(timing) &&
+                ['create', 'update', 'delete'].includes(operation) &&
+                entity
+              ) {
+                spec.triggerOn = {
+                  timing: timing as 'before' | 'after',
+                  operation: operation as 'create' | 'update' | 'delete',
+                  entity,
+                };
+              }
+            }
+            if (typeof wo.withRole === 'string' && wo.withRole) {
+              spec.withRole = wo.withRole;
+            }
+            return spec;
+          })
+          .filter((w) => w.name)
+      : [];
+
+    const agents: AgentSpec[] = Array.isArray(obj.agents)
+      ? obj.agents
+          .map((a: unknown) => {
+            const ao = a as Record<string, unknown>;
+            const capabilities: FeatureAnnotation[] = Array.isArray(
+              ao.capabilities,
+            )
+              ? ao.capabilities
+                  .map((c: unknown) => {
+                    const co = c as Record<string, unknown>;
+                    return {
+                      feature:
+                        typeof co.feature === 'string'
+                          ? co.feature
+                          : typeof co.capability === 'string'
+                            ? co.capability
+                            : '',
+                      rationale:
+                        typeof co.rationale === 'string' ? co.rationale : '',
+                    };
+                  })
+                  .filter((c) => c.feature)
+              : [];
+            return {
+              name: typeof ao.name === 'string' ? ao.name : '',
+              description:
+                typeof ao.description === 'string' ? ao.description : '',
+              goal: typeof ao.goal === 'string' ? ao.goal : '',
+              tools: Array.isArray(ao.tools)
+                ? ao.tools.filter((t): t is string => typeof t === 'string')
+                : [],
+              capabilities,
+            };
+          })
+          .filter((a) => a.name)
+      : [];
+
+    return {
+      appName,
+      dirName,
+      moduleName,
+      entities,
+      relationships,
+      events,
+      workflows,
+      agents,
+    };
+  }
+}
+
+export function designSpecToDescription(
+  spec: AppSpec,
+  baselineSpec?: AppSpec,
+): string {
+  const parts: string[] = [];
+
+  parts.push(
+    `Generate code for the "${spec.appName}" app (module: ${spec.moduleName}).`,
+  );
+
+  if (spec.entities.length > 0) {
+    parts.push('', '## Entities', '');
+    for (const e of spec.entities) {
+      parts.push(`- **${e.name}**: ${e.description}`);
+      if (e.features.length > 0) {
+        for (const f of e.features) {
+          parts.push(`  - ${f.feature}: ${f.rationale}`);
+        }
+      }
+    }
+  }
+
+  if (spec.relationships.length > 0) {
+    parts.push('', '## Relationships', '');
+    for (const r of spec.relationships) {
+      parts.push(
+        `- **${r.name}** (${r.kind}): ${r.between[0]} → ${r.between[1]} (@${r.type})`,
+      );
+      if (r.rationale) parts.push(`  Rationale: ${r.rationale}`);
+      if (r.roleAliases)
+        parts.push(
+          `  Role aliases: ${r.between[0]} @as ${r.roleAliases[0]}, ${r.between[1]} @as ${r.roleAliases[1]}`,
+        );
+      if (r.hasSchema)
+        parts.push(
+          `  Has schema: yes${r.hasSchemaRationale ? ` — ${r.hasSchemaRationale}` : ''}`,
+        );
+    }
+  }
+
+  if (spec.events.length > 0) {
+    parts.push('', '## Events', '');
+    for (const e of spec.events) {
+      const pub = e.public ? ' (@public)' : '';
+      parts.push(`- **${e.name}**${pub}: ${e.description}`);
+    }
+  }
+
+  if (spec.workflows.length > 0) {
+    parts.push('', '## Workflows', '');
+    for (const w of spec.workflows) {
+      if (w.triggerOn) {
+        parts.push(
+          `- **${w.name}** (trigger: @${w.triggerOn.timing} ${w.triggerOn.operation} ${w.triggerOn.entity}): ${w.description}`,
+        );
+      } else {
+        parts.push(`- **${w.name}**: ${w.description}`);
+      }
+      if (w.withRole) parts.push(`  Requires role: ${w.withRole}`);
+      if (w.dataTouched.length > 0)
+        parts.push(`  Data touched: ${w.dataTouched.join(', ')}`);
+    }
+  }
+
+  if (spec.agents.length > 0) {
+    parts.push('', '## Agents', '');
+    for (const a of spec.agents) {
+      parts.push(`- **${a.name}**: ${a.description}`);
+      if (a.goal) parts.push(`  Goal: ${a.goal}`);
+      if (a.tools.length > 0) parts.push(`  Tools: ${a.tools.join(', ')}`);
+      if (a.capabilities.length > 0) {
+        for (const c of a.capabilities) {
+          parts.push(`  - ${c.feature}: ${c.rationale}`);
+        }
+      }
+    }
+  }
+
+  if (baselineSpec && baselineSpec.entities.length > 0) {
+    parts.push(
+      '',
+      '## Baseline Entities (DO NOT redefine — reference only)',
+      '',
+    );
+    parts.push(
+      `The baseline module \`${baselineSpec.moduleName}\` provides these shared entities:`,
+    );
+    for (const e of baselineSpec.entities) {
+      parts.push(`- ${e.name}: ${e.description}`);
+    }
+    parts.push(
+      '',
+      'Reference them using fully-qualified names, e.g. `' +
+        baselineSpec.moduleName.replace('.core', '') +
+        '.core/' +
+        baselineSpec.entities[0].name +
+        '`',
+    );
+  }
+
+  return parts.join('\n');
+}