@agentlang/agentmanager 0.0.3 → 0.0.4

package/dist/apps/monolith/libs/agentcraft/src/prompts/resolver.prompt.js

@@ -0,0 +1,320 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildResolverSystemPrompt = buildResolverSystemPrompt;
+exports.parseResolverOutput = parseResolverOutput;
+exports.buildResolverMeta = buildResolverMeta;
+const output_writer_1 = require("../utils/output-writer");
+function toResolverAlias(name) {
+    const camelCase = name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    return camelCase + 'Resolver';
+}
+function buildResolverSystemPrompt(name, description, specContent) {
+    const filePrefix = name.replace(/-/g, '_') + '_resolver';
+    const jsFileName = filePrefix + '.js';
+    const alFileName = filePrefix + '.al';
+    const importAlias = toResolverAlias(name);
+    return `You are a resolver generator for agentlang applications. Your task is to generate a complete resolver package that allows agentlang entities to interact with an external API.
+
+## Resolver Name
+${name}
+
+## Description
+${description}
+
+## API Specification
+<api-spec>
+${specContent}
+</api-spec>
+
+## Agentlang Resolver Syntax Reference
+
+### Entity Definition (.al file)
+Entities are defined using the \`entity\` keyword inside a \`module\` block. Each entity has typed attributes and a \`resolver\` block that maps CRUD operations to functions imported from a JavaScript file. Each resolver block MUST have a unique name (NOT the entity name itself) and a **paths vector** \`[ModuleName/EntityName]\` that specifies which entity it resolves.
+
+Attribute types: \`String\`, \`Int\`, \`Float\`, \`Boolean\`, \`UUID\`, \`DateTime\`, \`Map\`
+Attribute properties: \`@id\` (primary key), \`@unique\`, \`@optional\`, \`@default(value)\`
+
+Attributes may also be declared as arrays, e.g String[].
+
+**Structures with no attributes MUST be defined with \`{}\`**. For example: \`@public event getAllPets {}\`, \`record EmptyPayload {}\`. Never omit the braces.
+
+**IMPORTANT — Resolver binding syntax:**
+
+The .al file MUST import the JavaScript file using an \`import\` statement with \`@as\` to create an alias. Resolver methods are then bound using \`alias.functionName\` (dot notation, NO quotes).
+
+\`\`\`
+module Resolvers.GitHub
+
+import "github_resolver.js" @as githubResolver
+
+entity Issue {
+    id        Int    @id,
+    title     String,
+    body      String @optional,
+    state     String @optional,
+    number    Int    @optional,
+    repo      String,
+    owner     String
+}
+
+resolver IssueResolver [Resolvers.GitHub/Issue] {
+    create  githubResolver.createIssue,
+    query   githubResolver.queryIssue,
+    update  githubResolver.updateIssue,
+    delete  githubResolver.deleteIssue
+}
+\`\`\`
+
+CRITICAL syntax rules:
+- Do NOT use the string-path format like \`"resolver.js/functionName"\`. That is INVALID. Always use \`import "file.js" @as alias\` at the top of the module, then \`alias.functionName\` in resolver blocks.
+- The resolver name MUST be a unique identifier (e.g. \`IssueResolver\`), NOT the entity name itself. \`resolver Issue { ... }\` is WRONG — use \`resolver IssueResolver [GitHub/Issue] { ... }\`.
+- The paths vector \`[ModuleName/EntityName]\` is REQUIRED. It tells agentlang which entity this resolver handles. The ModuleName is the last segment of the module name (e.g. for \`module Resolvers.GitHub\`, use \`GitHub/Issue\`).
+- Resolver method bindings MUST be separated by commas.
+
+### Resolver JS Implementation (${jsFileName})
+The resolver JS file exports functions for each CRUD operation. Each function receives an \`attributes\` object.
+
+- Use \`instance.attributes.get("fieldName")\` to read entity attribute values
+- Use \`instance.queryAttributes.get("fieldName")\` to get values to query entity instances
+- Use \`process.env.ENV_VAR_NAME\` to read environment variables (for auth tokens, API keys, etc.). Do NOT import \`getLocalEnv\` or similar abstractions from agentlang.
+- Use the global \`fetch\` API for HTTP calls
+- Return result objects matching the entity shape
+- Throw errors with descriptive messages on failure
+
+\`\`\`javascript
+async function createIssue(_, instance) { // the first argument '_' is always required for resolver methods
+    const token = process.env.GITHUB_TOKEN;
+    const owner = instance.attributes.get("owner");
+    const repo = instance.attributes.get("repo");
+    const title = instance.attributes.get("title");
+    const body = instance.attributes.get("body");
+
+    const response = await fetch(
+        \`https://api.github.com/repos/\${owner}/\${repo}/issues\`,
+        {
+            method: "POST",
+            headers: {
+                "Authorization": \`Bearer \${token}\`,
+                "Accept": "application/vnd.github+json",
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({ title, body })
+        }
+    );
+
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(\`GitHub API error: \${response.status} \${error}\`);
+    }
+
+    const issue = await response.json();
+    return {
+        id: issue.id,
+        number: issue.number,
+        title: issue.title,
+        body: issue.body,
+        state: issue.state,
+        repo,
+        owner
+    }
+}
+
+async function queryIssue(_, instance) {
+    const token = process.env.GITHUB_TOKEN;
+    const owner = instance.queryAttributes.get("owner");
+    const repo = instance.queryAttributes.get("repo");
+
+    const response = await fetch(
+        \`https://api.github.com/repos/\${owner}/\${repo}/issues\`,
+        {
+            headers: {
+                "Authorization": \`Bearer \${token}\`,
+                "Accept": "application/vnd.github+json"
+            }
+        }
+    );
+
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(\`GitHub API error: \${response.status} \${error}\`);
+    }
+
+    const issues = await response.json();
+    return issues.map(issue => ({
+        id: issue.id,
+        number: issue.number,
+        title: issue.title,
+        body: issue.body,
+        state: issue.state,
+        repo,
+        owner
+    }));
+}
+
+async function updateIssue(_, instance) {
+    const token = process.env.GITHUB_TOKEN;
+    const owner = instance.attributes.get("owner");
+    const repo = instance.attributes.get("repo");
+    const number = instance.attributes.get("number");
+    const title = instance.attributes.get("title");
+    const body = instance.attributes.get("body");
+    const state = instance.attributes.get("state");
+
+    const updates = {};
+    if (title) updates.title = title;
+    if (body) updates.body = body;
+    if (state) updates.state = state;
+
+    const response = await fetch(
+        \`https://api.github.com/repos/\${owner}/\${repo}/issues/\${number}\`,
+        {
+            method: "PATCH",
+            headers: {
+                "Authorization": \`Bearer \${token}\`,
+                "Accept": "application/vnd.github+json",
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(updates)
+        }
+    );
+
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(\`GitHub API error: \${response.status} \${error}\`);
+    }
+
+    const issue = await response.json();
+    return {
+        id: issue.id,
+        number: issue.number,
+        title: issue.title,
+        body: issue.body,
+        state: issue.state,
+        repo,
+        owner
+    };
+}
+
+async function deleteIssue(_, instance) {
+    const token = process.env.GITHUB_TOKEN;
+    const owner = instance.attributes.get("owner");
+    const repo = instance.attributes.get("repo");
+    const number = instance.attributes.get("number");
+
+    // GitHub API doesn't support deleting issues, so we close it instead
+    const response = await fetch(
+        \`https://api.github.com/repos/\${owner}/\${repo}/issues/\${number}\`,
+        {
+            method: "PATCH",
+            headers: {
+                "Authorization": \`Bearer \${token}\`,
+                "Accept": "application/vnd.github+json",
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({ state: "closed" })
+        }
+    );
+
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(\`GitHub API error: \${response.status} \${error}\`);
+    }
+
+    return { id: 0, title: "", repo, owner };
+}
+
+export { createIssue, queryIssue, updateIssue, deleteIssue };
+\`\`\`
+
+### package.json
+\`\`\`json
+{
+    "name": "${name}-resolver",
+    "version": "0.1.0",
+    "type": "module"
+}
+\`\`\`
+
+## Output Format
+
+Output exactly three files using this delimiter format:
+
+\`\`\`
+--- FILE: src/${alFileName} ---
+<module definition with import statement and entities with resolver mappings>
+
+--- FILE: src/${jsFileName} ---
+<JavaScript implementation with CRUD functions>
+
+--- FILE: package.json ---
+<package.json with name, version, type>
+\`\`\`
+
+## Reserved Words — Do NOT Use as Names
+
+Agentlang reserves certain keywords. You MUST NOT use any of the following as entity names or attribute names. If your domain has a concept that matches a reserved word, rename it (e.g. \`Event\` → \`CalendarEvent\`, \`Flow\` → \`AppFlow\`, \`Agent\` → \`AIAgent\`, \`import\` → \`importItem\`, \`delete\` → \`isDeleted\`, \`record\` → \`entry\`).
+
+**Definition keywords:** \`module\`, \`import\`, \`entity\`, \`event\`, \`record\`, \`relationship\`, \`workflow\`, \`agent\`, \`resolver\`, \`flow\`, \`decision\`, \`scenario\`, \`directive\`, \`glossaryEntry\`, \`eval\`
+
+**Control flow and operators:** \`if\`, \`else\`, \`for\`, \`in\`, \`return\`, \`throw\`, \`await\`, \`delete\`, \`purge\`, \`case\`, \`not\`, \`true\`, \`false\`, \`or\`, \`and\`, \`like\`, \`between\`
+
+**CRUD and schema keywords:** \`create\`, \`update\`, \`query\`, \`upsert\`, \`contains\`, \`extends\`, \`where\`, \`roles\`, \`allow\`, \`subscribe\`, \`backoff\`, \`attempts\`
+
+## Guidelines
+- Focus on the described functionality: "${description}"
+- Handle authentication via environment variables using \`process.env\` (e.g. \`process.env.PETSTORE_API_KEY\`). Do NOT import \`getLocalEnv\` or similar abstractions from agentlang.
+- Use the global \`fetch\` API for all HTTP requests
+- Include proper error handling with descriptive error messages
+- Map API responses back to entity attribute shapes
+- Module name should follow the pattern \`Resolvers.<PascalCaseName>\`
+- Each entity needs a matching resolver block with a unique resolver name (e.g. \`PetResolver\`, \`OrderResolver\`) and a paths vector \`[ModuleName/EntityName]\`. Resolver method bindings must be comma-separated
+- Export all resolver functions from ${jsFileName}
+- The .al file MUST start with \`import "${jsFileName}" @as ${importAlias}\` right after the module declaration
+- Resolver methods MUST use \`${importAlias}.functionName\` (dot notation), NEVER \`"file/function"\` string syntax`;
+}
+function parseResolverOutput(rawOutput) {
+    const files = (0, output_writer_1.parseAssemblyOutput)(rawOutput);
+    let al = '';
+    let js = '';
+    for (const file of files) {
+        if (file.filePath.endsWith('.al')) {
+            al = file.content;
+        }
+        else if (file.filePath.endsWith('.js')) {
+            js = file.content;
+        }
+    }
+    if (!al && !js) {
+        return null;
+    }
+    const meta = buildResolverMeta(al);
+    return { al, js, meta, rawOutput };
+}
+function buildResolverMeta(alContent) {
+    const lines = ['# Resolver Metadata', ''];
+    const moduleMatch = alContent.match(/^module\s+(\S+)/m);
+    if (moduleMatch) {
+        lines.push(`Module: ${moduleMatch[1]}`);
+        lines.push('');
+    }
+    const entityRe = /entity\s+(\w+)\s*\{([^}]*)\}/g;
+    let match;
+    while ((match = entityRe.exec(alContent)) !== null) {
+        const entityName = match[1];
+        const body = match[2];
+        lines.push(`## Entity: ${entityName}`);
+        const attrRe = /(\w+)\s+(String|Int|Float|Boolean|UUID|DateTime|Map|Any|Number|Decimal|Email|Date|Time|URL|Password)(?:\[\])?\s*([^,\n]*)/g;
+        let attrMatch;
+        const attrs = [];
+        while ((attrMatch = attrRe.exec(body)) !== null) {
+            attrs.push(`- ${attrMatch[1]}: ${attrMatch[2]}${attrMatch[3].trim() ? ' ' + attrMatch[3].trim() : ''}`);
+        }
+        if (attrs.length > 0) {
+            lines.push('Attributes:');
+            lines.push(...attrs);
+        }
+        lines.push('');
+    }
+    return lines.join('\n').trim();
+}
+//# sourceMappingURL=resolver.prompt.js.map

package/dist/apps/monolith/libs/agentcraft/src/prompts/resolver.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.prompt.js","sourceRoot":"","sources":["../../../../../../../libs/agentcraft/src/prompts/resolver.prompt.ts"],"names":[],"mappings":"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"}

package/dist/apps/monolith/libs/agentcraft/src/prompts/semantics-guide.d.ts

@@ -0,0 +1 @@
+export declare const SEMANTICS_GUIDE = "## Agentlang Semantics Guide\n\nAgentlang is a declarative language for building AI-powered applications. An application is a **module** containing entities, relationships, events, workflows, and agents. Understanding when to use each construct is critical for correct design.\n\n### Entity\n\nAn entity is a **persistent, database-backed domain object**. Every noun in your domain that needs to be stored, queried, or referenced is an entity. Examples: User, Product, Order, Lead, Ticket.\n\nAt design time, define entities with a name and description only \u2014 attributes are added during code generation. Focus on identifying the right set of entities: too few leads to overloaded entities; too many leads to unnecessary complexity.\n\n**When to define an entity:** Any domain concept that has its own identity and lifecycle, needs CRUD operations, or is referenced by other constructs.\n\n**When NOT to define an entity:** Temporary data, computed values, or concepts that only exist within a single workflow step.\n\n**Inheritance:** An entity can extend a record or another entity to inherit its attributes. Use when multiple entities share a common set of fields.\n\n**Entity-level features** (important design decisions \u2014 mark which ones apply to each entity):\n\n- **@meta {\"audit\": true}** \u2014 Enable audit trail. Use when you need to track who changed what and when (e.g., compliance-sensitive entities like Orders, Payments, MedicalRecords).\n- **@meta {\"fullTextSearch\": \"*\"}** \u2014 Enable full-text search. Use when users need to search entity instances by free-text queries (e.g., Tickets, Articles, Products).\n- **@rbac** \u2014 Role-based access control at the entity level. Define which roles can create/read/update/delete, and optional row-level filters (e.g., \"users can only read their own records\"). Use when different user roles need different access levels.\n- **@before/@after triggers** \u2014 Lifecycle hooks that fire before or after create/update/delete operations. Use when an entity change should automatically trigger side effects (e.g., after creating a Ticket, auto-assign it; before updating an Order, validate inventory). Triggers reference events/workflows by name and can be @async.\n- **@with_unique(attr1, attr2)** \u2014 Composite unique constraint across multiple attributes. Use when no single attribute is unique but the combination must be (e.g., unique email per organization, unique document per version).\n- **@actions** \u2014 Bind named actions to events on an entity. Use when an entity needs custom operations beyond standard CRUD.\n- **@expr** \u2014 Computed attributes whose values are automatically derived from other fields. Use when a field's value can always be calculated from other attributes (e.g., totalPrice = quantity * unitPrice). User-provided values override the computed expression.\n\n### Relationship\n\nRelationships connect entities. There are exactly two kinds \u2014 choosing the right one is a critical design decision.\n\n**contains (parent-child ownership):**\n- The parent **owns** the child. The child's identity is scoped within the parent.\n- Deleting the parent cascades to delete all children.\n- The child has no meaning outside its parent.\n- Use for: Orders containing OrderItems, Users containing Posts, Projects containing Tasks.\n\n**between (cross-reference association):**\n- Both entities have **independent lifecycles**. Neither owns the other.\n- Deleting one side does NOT delete the other.\n- Supports cardinality: one_one, one_many (default is many-to-many).\n- Use for: Students enrolled in Courses, Employees assigned to Departments, Tags on Articles.\n\n**Decision framework:** Ask \"If I delete entity A, should entity B also be deleted?\" If yes \u2192 contains. If no \u2192 between.\n\n**Cardinality for between relationships:**\n- one_one: Each A has exactly one B, and vice versa (e.g., User \u2194 Profile).\n- one_many: Each A has many Bs, but each B belongs to one A (e.g., Department \u2192 Employees).\n- many_many (default): Each A can relate to many Bs and vice versa (e.g., Students \u2194 Courses).\n\n**Role aliases (@as):** When a relationship connects an entity to itself (self-referencing), use @as to distinguish the two roles. Example: Employee @as manager \u2194 Employee @as report. Use when modeling hierarchies, mentorship, or any self-referential relationship.\n\n**Relationship schemas:** A relationship can carry its own attributes (e.g., Enrollment between Student and Course might have enrolledOn and grade). Use when the association itself has data beyond just linking two entities.\n\n### Event\n\nAn event is a **command or action** that triggers a workflow. It defines the input data schema for that action.\n\n- @public events expose a REST API endpoint (POST /api/Module/EventName).\n- Events can extend a record or another event to inherit attributes.\n- Events represent user actions (SubmitOrder, ApproveApplication) or system triggers (ProcessPayment, SendNotification).\n- Event names should clearly describe the action being performed.\n\n**When to define an event:** Any action that initiates a process, changes state, or triggers side effects.\n\n### Workflow\n\nA workflow is the **procedural handler** for an event or a lifecycle trigger. It performs CRUD operations on entities, invokes agents, and orchestrates multi-step logic.\n\n**Two forms:**\n\n1. **Event-driven (named):** The workflow name matches the event name. When the event fires, the workflow executes.\n2. **Lifecycle trigger:** Fires automatically before or after an entity's create, update, or delete operation. Use for automatic side effects (e.g., after creating a User, create a default Profile; before deleting an Order, check it's not shipped).\n\n**Access control:** @withRole restricts who can invoke a workflow (e.g., only admins can run an approval workflow).\n\n**What workflows can do:**\n- **CRUD operations** \u2014 Create, query (with ? suffix), update, upsert, delete, and purge entity instances.\n- **Sequential binding** \u2014 Chain operations with @as to bind results to variables for subsequent steps.\n- **Control flow** \u2014 if/else conditionals and for-each loops over collections.\n- **Error handling** \u2014 @catch for not_found and error cases; @empty for handling empty query results with fallback logic.\n- **Side effects** \u2014 @then for post-operation logic (run additional statements after a create/update).\n- **Joins and analytics** \u2014 Query across entities with @join/@left_join/@right_join/@full_join, project results with @into, filter with @where, aggregate with @count/@sum/@avg/@min/@max, group with @groupBy, sort with @orderBy, paginate with @limit/@offset, deduplicate with @distinct.\n- **Upsert** \u2014 @upsert for create-or-update semantics.\n- **Full-text search** \u2014 Query entities using free-text when @meta fullTextSearch is enabled.\n- **Return and throw** \u2014 Return results or throw errors to abort with a message.\n\n**When to define a workflow:** Every event needs a corresponding workflow. Lifecycle triggers are for automatic side effects on entity operations. The workflow describes WHAT happens \u2014 which entities are read, created, updated, or deleted.\n\n### Agent\n\nAn agent is an **AI-powered component** using an LLM. Agents understand natural language, make decisions, classify data, generate content, and interact with entities via tools.\n\n- Tools are the entities, events, and workflows an agent can call.\n- @public agents expose a REST chat endpoint.\n- Each agent should have a focused role \u2014 one agent per domain area.\n\n**When to define an agent:** Any task requiring natural language understanding, classification, content generation, or intelligent decision-making. Agents are NOT needed for simple CRUD \u2014 workflows handle that directly.\n\n**Agent goal:** Each agent should have a clear high-level objective explaining its purpose in the system. The goal answers \"why does this agent exist and what value does it provide?\"\n\n**Key agent capabilities** (design decisions \u2014 note which ones each agent needs):\n\n- **responseSchema** \u2014 Force the agent to return structured output matching a record type. Use when downstream code needs to process the agent's output programmatically (e.g., a classification agent returning a typed result).\n- **documents** \u2014 Attach documents for RAG (retrieval-augmented generation). Use when the agent needs access to reference material (e.g., product manuals, pricing lists, policy documents).\n- **validate** \u2014 Run a validation workflow on the agent's output before accepting it. Use when the agent's output must meet specific business rules.\n- **retry** \u2014 Retry policy for failed agent invocations. Use when the agent's task is critical and transient failures are possible.\n- **stateless** \u2014 If true, the agent has no conversation history. Use for one-shot classification or transformation tasks that don't need context from previous interactions.\n- **scratch** \u2014 Temporary mutable variables available during the agent's execution. Use when the agent needs working memory across tool calls within a single interaction.\n- **compact** \u2014 Number of conversation turns before older messages are summarized and discarded. Use for long-running agents to prevent context overflow.\n\n### Flow (Advanced)\n\nA flow is an **orchestration pipeline** connecting multiple agents and decision points. Use when a complex process requires sequential agent invocations with routing logic.\n\n**When to define a flow:** Multi-step AI processes where one agent's output feeds another, with conditional routing between them. Most applications don't need flows \u2014 they are for complex orchestration scenarios.\n\n### How Constructs Compose\n\nThe typical pattern is:\n1. **Entities** hold the data (the nouns)\n2. **Relationships** define how entities connect\n3. **Events** represent actions users or systems can take (the verbs)\n4. **Workflows** handle events by reading/writing entities\n5. **Agents** add intelligence \u2014 they are invoked by workflows when AI reasoning is needed\n6. **Flows** orchestrate multiple agents for complex multi-step AI processes\n";

package/dist/apps/monolith/libs/agentcraft/src/prompts/semantics-guide.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEMANTICS_GUIDE = void 0;
+exports.SEMANTICS_GUIDE = `## Agentlang Semantics Guide
+
+Agentlang is a declarative language for building AI-powered applications. An application is a **module** containing entities, relationships, events, workflows, and agents. Understanding when to use each construct is critical for correct design.
+
+### Entity
+
+An entity is a **persistent, database-backed domain object**. Every noun in your domain that needs to be stored, queried, or referenced is an entity. Examples: User, Product, Order, Lead, Ticket.
+
+At design time, define entities with a name and description only — attributes are added during code generation. Focus on identifying the right set of entities: too few leads to overloaded entities; too many leads to unnecessary complexity.
+
+**When to define an entity:** Any domain concept that has its own identity and lifecycle, needs CRUD operations, or is referenced by other constructs.
+
+**When NOT to define an entity:** Temporary data, computed values, or concepts that only exist within a single workflow step.
+
+**Inheritance:** An entity can extend a record or another entity to inherit its attributes. Use when multiple entities share a common set of fields.
+
+**Entity-level features** (important design decisions — mark which ones apply to each entity):
+
+- **@meta {"audit": true}** — Enable audit trail. Use when you need to track who changed what and when (e.g., compliance-sensitive entities like Orders, Payments, MedicalRecords).
+- **@meta {"fullTextSearch": "\*"}** — Enable full-text search. Use when users need to search entity instances by free-text queries (e.g., Tickets, Articles, Products).
+- **@rbac** — Role-based access control at the entity level. Define which roles can create/read/update/delete, and optional row-level filters (e.g., "users can only read their own records"). Use when different user roles need different access levels.
+- **@before/@after triggers** — Lifecycle hooks that fire before or after create/update/delete operations. Use when an entity change should automatically trigger side effects (e.g., after creating a Ticket, auto-assign it; before updating an Order, validate inventory). Triggers reference events/workflows by name and can be @async.
+- **@with_unique(attr1, attr2)** — Composite unique constraint across multiple attributes. Use when no single attribute is unique but the combination must be (e.g., unique email per organization, unique document per version).
+- **@actions** — Bind named actions to events on an entity. Use when an entity needs custom operations beyond standard CRUD.
+- **@expr** — Computed attributes whose values are automatically derived from other fields. Use when a field's value can always be calculated from other attributes (e.g., totalPrice = quantity * unitPrice). User-provided values override the computed expression.
+
+### Relationship
+
+Relationships connect entities. There are exactly two kinds — choosing the right one is a critical design decision.
+
+**contains (parent-child ownership):**
+- The parent **owns** the child. The child's identity is scoped within the parent.
+- Deleting the parent cascades to delete all children.
+- The child has no meaning outside its parent.
+- Use for: Orders containing OrderItems, Users containing Posts, Projects containing Tasks.
+
+**between (cross-reference association):**
+- Both entities have **independent lifecycles**. Neither owns the other.
+- Deleting one side does NOT delete the other.
+- Supports cardinality: one_one, one_many (default is many-to-many).
+- Use for: Students enrolled in Courses, Employees assigned to Departments, Tags on Articles.
+
+**Decision framework:** Ask "If I delete entity A, should entity B also be deleted?" If yes → contains. If no → between.
+
+**Cardinality for between relationships:**
+- one_one: Each A has exactly one B, and vice versa (e.g., User ↔ Profile).
+- one_many: Each A has many Bs, but each B belongs to one A (e.g., Department → Employees).
+- many_many (default): Each A can relate to many Bs and vice versa (e.g., Students ↔ Courses).
+
+**Role aliases (@as):** When a relationship connects an entity to itself (self-referencing), use @as to distinguish the two roles. Example: Employee @as manager ↔ Employee @as report. Use when modeling hierarchies, mentorship, or any self-referential relationship.
+
+**Relationship schemas:** A relationship can carry its own attributes (e.g., Enrollment between Student and Course might have enrolledOn and grade). Use when the association itself has data beyond just linking two entities.
+
+### Event
+
+An event is a **command or action** that triggers a workflow. It defines the input data schema for that action.
+
+- @public events expose a REST API endpoint (POST /api/Module/EventName).
+- Events can extend a record or another event to inherit attributes.
+- Events represent user actions (SubmitOrder, ApproveApplication) or system triggers (ProcessPayment, SendNotification).
+- Event names should clearly describe the action being performed.
+
+**When to define an event:** Any action that initiates a process, changes state, or triggers side effects.
+
+### Workflow
+
+A workflow is the **procedural handler** for an event or a lifecycle trigger. It performs CRUD operations on entities, invokes agents, and orchestrates multi-step logic.
+
+**Two forms:**
+
+1. **Event-driven (named):** The workflow name matches the event name. When the event fires, the workflow executes.
+2. **Lifecycle trigger:** Fires automatically before or after an entity's create, update, or delete operation. Use for automatic side effects (e.g., after creating a User, create a default Profile; before deleting an Order, check it's not shipped).
+
+**Access control:** @withRole restricts who can invoke a workflow (e.g., only admins can run an approval workflow).
+
+**What workflows can do:**
+- **CRUD operations** — Create, query (with ? suffix), update, upsert, delete, and purge entity instances.
+- **Sequential binding** — Chain operations with @as to bind results to variables for subsequent steps.
+- **Control flow** — if/else conditionals and for-each loops over collections.
+- **Error handling** — @catch for not_found and error cases; @empty for handling empty query results with fallback logic.
+- **Side effects** — @then for post-operation logic (run additional statements after a create/update).
+- **Joins and analytics** — Query across entities with @join/@left_join/@right_join/@full_join, project results with @into, filter with @where, aggregate with @count/@sum/@avg/@min/@max, group with @groupBy, sort with @orderBy, paginate with @limit/@offset, deduplicate with @distinct.
+- **Upsert** — @upsert for create-or-update semantics.
+- **Full-text search** — Query entities using free-text when @meta fullTextSearch is enabled.
+- **Return and throw** — Return results or throw errors to abort with a message.
+
+**When to define a workflow:** Every event needs a corresponding workflow. Lifecycle triggers are for automatic side effects on entity operations. The workflow describes WHAT happens — which entities are read, created, updated, or deleted.
+
+### Agent
+
+An agent is an **AI-powered component** using an LLM. Agents understand natural language, make decisions, classify data, generate content, and interact with entities via tools.
+
+- Tools are the entities, events, and workflows an agent can call.
+- @public agents expose a REST chat endpoint.
+- Each agent should have a focused role — one agent per domain area.
+
+**When to define an agent:** Any task requiring natural language understanding, classification, content generation, or intelligent decision-making. Agents are NOT needed for simple CRUD — workflows handle that directly.
+
+**Agent goal:** Each agent should have a clear high-level objective explaining its purpose in the system. The goal answers "why does this agent exist and what value does it provide?"
+
+**Key agent capabilities** (design decisions — note which ones each agent needs):
+
+- **responseSchema** — Force the agent to return structured output matching a record type. Use when downstream code needs to process the agent's output programmatically (e.g., a classification agent returning a typed result).
+- **documents** — Attach documents for RAG (retrieval-augmented generation). Use when the agent needs access to reference material (e.g., product manuals, pricing lists, policy documents).
+- **validate** — Run a validation workflow on the agent's output before accepting it. Use when the agent's output must meet specific business rules.
+- **retry** — Retry policy for failed agent invocations. Use when the agent's task is critical and transient failures are possible.
+- **stateless** — If true, the agent has no conversation history. Use for one-shot classification or transformation tasks that don't need context from previous interactions.
+- **scratch** — Temporary mutable variables available during the agent's execution. Use when the agent needs working memory across tool calls within a single interaction.
+- **compact** — Number of conversation turns before older messages are summarized and discarded. Use for long-running agents to prevent context overflow.
+
+### Flow (Advanced)
+
+A flow is an **orchestration pipeline** connecting multiple agents and decision points. Use when a complex process requires sequential agent invocations with routing logic.
+
+**When to define a flow:** Multi-step AI processes where one agent's output feeds another, with conditional routing between them. Most applications don't need flows — they are for complex orchestration scenarios.
+
+### How Constructs Compose
+
+The typical pattern is:
+1. **Entities** hold the data (the nouns)
+2. **Relationships** define how entities connect
+3. **Events** represent actions users or systems can take (the verbs)
+4. **Workflows** handle events by reading/writing entities
+5. **Agents** add intelligence — they are invoked by workflows when AI reasoning is needed
+6. **Flows** orchestrate multiple agents for complex multi-step AI processes
+`;
+//# sourceMappingURL=semantics-guide.js.map

package/dist/apps/monolith/libs/agentcraft/src/prompts/semantics-guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantics-guide.js","sourceRoot":"","sources":["../../../../../../../libs/agentcraft/src/prompts/semantics-guide.ts"],"names":[],"mappings":";;;AAQa,QAAA,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6H9B,CAAC"}

package/dist/apps/monolith/libs/agentcraft/src/services/anthropic-craft-llm.service.d.ts

@@ -0,0 +1,13 @@
+import { CraftLlmProvider } from '../interfaces/llm-provider.interface';
+import { ChatRequest, ChatResponse } from '../types/llm.types';
+export declare class AnthropicCraftLlmService implements CraftLlmProvider {
+    private client;
+    private model;
+    private maxRetries;
+    private baseDelay;
+    constructor(model: string, apiKey: string);
+    chat(request: ChatRequest): Promise<ChatResponse>;
+    chatStream(request: ChatRequest, onChunk: (text: string) => void): Promise<ChatResponse>;
+    private withRetry;
+    private isRetryable;
+}

package/dist/apps/monolith/libs/agentcraft/src/services/anthropic-craft-llm.service.js

@@ -0,0 +1,167 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnthropicCraftLlmService = void 0;
+const common_1 = require("@nestjs/common");
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+let AnthropicCraftLlmService = class AnthropicCraftLlmService {
+    client;
+    model;
+    maxRetries = 3;
+    baseDelay = 1000;
+    constructor(model, apiKey) {
+        this.client = new sdk_1.default({ apiKey });
+        this.model = model;
+    }
+    async chat(request) {
+        return this.withRetry(async () => {
+            const useCache = request.cacheControl ?? false;
+            const params = {
+                model: this.model,
+                max_tokens: request.maxTokens ?? 16384,
+                system: useCache
+                    ? [
+                        {
+                            type: 'text',
+                            text: request.system,
+                            cache_control: { type: 'ephemeral' },
+                        },
+                    ]
+                    : request.system,
+                messages: request.messages.map((m) => ({
+                    role: m.role,
+                    content: typeof m.content === 'string'
+                        ? m.content
+                        : m.content
+                            .filter((b) => b.type === 'text')
+                            .map((b) => b.text)
+                            .join(''),
+                })),
+            };
+            if (request.tools?.length) {
+                params.tools = request.tools.map((t, i) => ({
+                    name: t.name,
+                    description: t.description ?? '',
+                    input_schema: t.inputSchema,
+                    ...(useCache && i === request.tools.length - 1
+                        ? { cache_control: { type: 'ephemeral' } }
+                        : {}),
+                }));
+            }
+            if (request.toolChoice) {
+                params.tool_choice = {
+                    type: 'tool',
+                    name: request.toolChoice.name,
+                };
+            }
+            const stream = this.client.messages.stream(params);
+            for await (const event of stream) {
+                void event;
+            }
+            const response = await stream.finalMessage();
+            const content = response.content
+                .filter((block) => block.type === 'text')
+                .map((block) => block.text)
+                .join('');
+            const toolCalls = response.content
+                .filter((block) => block.type === 'tool_use')
+                .map((block) => ({
+                id: block.id,
+                name: block.name,
+                input: block.input,
+            }));
+            return {
+                content: [{ type: 'text', text: content }],
+                stopReason: response.stop_reason === 'max_tokens' ? 'max_tokens' : 'end_turn',
+                toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+                truncated: response.stop_reason === 'max_tokens',
+                usage: {
+                    inputTokens: response.usage.input_tokens,
+                    outputTokens: response.usage.output_tokens,
+                    cacheCreationInputTokens: response.usage.cache_creation_input_tokens ?? undefined,
+                    cacheReadInputTokens: response.usage.cache_read_input_tokens ?? undefined,
+                },
+            };
+        });
+    }
+    async chatStream(request, onChunk) {
+        return this.withRetry(async () => {
+            const stream = this.client.messages.stream({
+                model: this.model,
+                max_tokens: request.maxTokens ?? 16384,
+                system: request.system,
+                messages: request.messages.map((m) => ({
+                    role: m.role,
+                    content: typeof m.content === 'string'
+                        ? m.content
+                        : m.content
+                            .filter((b) => b.type === 'text')
+                            .map((b) => b.text)
+                            .join(''),
+                })),
+            });
+            let fullContent = '';
+            for await (const event of stream) {
+                if (event.type === 'content_block_delta' &&
+                    event.delta.type === 'text_delta') {
+                    onChunk(event.delta.text);
+                    fullContent += event.delta.text;
+                }
+            }
+            const finalMessage = await stream.finalMessage();
+            return {
+                content: [{ type: 'text', text: fullContent }],
+                stopReason: finalMessage.stop_reason === 'max_tokens' ? 'max_tokens' : 'end_turn',
+                usage: {
+                    inputTokens: finalMessage.usage.input_tokens,
+                    outputTokens: finalMessage.usage.output_tokens,
+                },
+            };
+        });
+    }
+    async withRetry(fn) {
+        let lastError;
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                lastError = err;
+                if (!this.isRetryable(lastError) || attempt === this.maxRetries - 1) {
+                    throw lastError;
+                }
+                const delay = this.baseDelay * Math.pow(2, attempt);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+        throw lastError;
+    }
+    isRetryable(error) {
+        const message = error.message.toLowerCase();
+        return (message.includes('rate limit') ||
+            message.includes('429') ||
+            message.includes('500') ||
+            message.includes('502') ||
+            message.includes('503') ||
+            message.includes('network') ||
+            message.includes('timeout') ||
+            message.includes('econnreset'));
+    }
+};
+exports.AnthropicCraftLlmService = AnthropicCraftLlmService;
+exports.AnthropicCraftLlmService = AnthropicCraftLlmService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [String, String])
+], AnthropicCraftLlmService);
+//# sourceMappingURL=anthropic-craft-llm.service.js.map