npm - @atlashub/smartstack-cli - Versions diffs - 4.80.0 → 5.0.0 - Mend

@atlashub/smartstack-cli 4.80.0 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1008) hide show

package/templates/skills/admin/SKILL.md DELETED Viewed

@@ -1,48 +0,0 @@
----
-name: admin
-description: Admin account management - reset passwords, manage local admin accounts
-argument-hint: "<subcommand> [options]"
-disable-model-invocation: true
----
-<objective>
-Manage SmartStack admin accounts. Wraps the `smartstack admin` CLI command with guided workflows.
-**WARNING:** This skill modifies database records directly. Always confirm before executing.
-</objective>
-<quick_start>
-```bash
-/admin reset              # Reset local admin password (guided)
-/admin reset --force      # Reset without confirmation
-```
-</quick_start>
-<workflow>
-## Subcommands
-| Command | Description |
-|---------|-------------|
-| `/admin reset` | Reset the localAdmin account password |
-## /admin reset
-1. **Detect SmartStack.app** - Look for `.smartstack/config.json` or `SmartStack.Api/` directory
-2. **Run CLI command:**
-   ```bash
-   smartstack admin reset
-   ```
-3. **If `--force` flag passed:**
-   ```bash
-   smartstack admin reset --force
-   ```
-4. **Report result** - Show new credentials or error message
-</workflow>
-<success_criteria>
-- Admin command executed successfully or clear error displayed
-- New credentials shown to user (for reset)
-- SmartStack.app project correctly detected
-</success_criteria>

package/templates/skills/ai-prompt/SKILL.md DELETED Viewed

@@ -1,171 +0,0 @@
----
-name: ai-prompt
-description: |
-  Integrates AI capabilities into SmartStack features.
-  Use this skill when:
-  - User wants to integrate AI into a feature
-  - User mentions "prompt", "GPT", "Claude", "IA", "AI"
-  - Creating an assistant or chatbot
-  - Automatic content generation
-  - AI response validation with schema
-  Types: Prompt, OutputSchema, Provider, Model
----
-# Skill AI Prompt SmartStack
-> **Architecture:** Prompt + Blocks -> Provider + Model -> Completion -> Schema Validation
-> Multi-provider: OpenAI, Anthropic (Claude), Azure OpenAI, Google Gemini
-**Reference:** [_shared.md](../_shared.md) for common patterns
-## When This Skill Activates
-| Trigger | Example |
-|---------|---------|
-| Explicit request | "Integrate GPT to generate descriptions" |
-| Chatbot/Assistant | "Create an assistant for support" |
-| Content generation | "Auto-generate responses" |
-| Text analysis | "Analyze the sentiment of comments" |
-| Keywords | "prompt", "GPT", "Claude", "IA", "completion", "LLM" |
-## AI Flow
-```
-Feature -> IAiCompletionService.ExecutePromptAsync()
-    |
-Prompt + Blocks -> Provider Instance -> External API (OpenAI/Claude/Azure/Gemini)
-    |
-AI Response -> OutputSchema Validation -> Typed Result<T>
-```
-## Main Entities
-### AiProvider & AiModel
-- **Providers:** OpenAI, Anthropic, Azure OpenAI, Google
-- **Models:** gpt-4o, claude-opus-4-6/sonnet-4-6/haiku-4-5, gemini-pro
-- Properties: Code, ContextWindow, MaxOutputTokens, InputCost, OutputCost, SupportsVision, SupportsStreaming
-### AiProviderInstance
-Configured instance: Code, Name, SystemContext, DefaultModel, MonthlyBudgetLimit, EncryptedApiKey
-### Prompt & PromptBlock
-```csharp
-// Prompt: Code, Name, Version, Status, IsTemplate, OutputSchemaId, Blocks
-// PromptBlockType: System, User, Assistant, Tool, Context, Examples
-// Block: Label, Content, DisplayOrder, IsRequired, Condition
-```
-### OutputSchema
-JSON Schema for validation: Code, Name, JsonSchema, DotNetType
-### AiAgent (R17 — v3.46+)
-Multi-step agent with reasoning modes. See [references/ai-agent-modes.md](references/ai-agent-modes.md).
-- **AiAgentMode** : `Sequential` (0), `ReAct` (1), `PlanAndExecute` (2), `SelfCorrection` (3)
-- **AiAgentStepRole** : `Worker` (0), `Planner` (1), `Reasoner` (2), `Critic` (3), `Synthesizer` (4)
-- **MaxIterations** (default 5, range 1-20) — protects against infinite loops
-- **QualityThreshold** (default 0.8) — used by `SelfCorrection` mode
-- **AiSkill.CacheTtlSeconds** + **AiSkillBlock.IsCacheable** — caching for idempotent outputs
-Default to `Sequential` ; switch to `ReAct`/`PlanAndExecute`/`SelfCorrection` only when needed (cost/latency impact).
-### AiTool — function calling (R2 — v3.46+)
-Server-side function the model can decide to invoke during a completion. Tools turn skills from one-shot prompts into agentic workflows that can read live data, call external APIs, and condition output on the result.
-```csharp
-class AiTool : BaseEntity, IAuditableEntity
-{
-    public string Name { get; }                  // Snake_case, presented to model: "search_database"
-    public string DisplayName { get; }           // Admin UI label
-    public string Description { get; }           // Drives model decision — short, action-oriented
-    public string ParametersSchemaJson { get; }  // JSON Schema of tool arguments
-    public string HandlerKey { get; }            // Stable key → IToolHandler dispatcher
-    public Guid ModuleId { get; }                // Module owns the tool (permissions + admin grouping)
-    public bool IsActive { get; }
-}
-```
-- **Many-to-many** with `AiSkill` via `AiSkillTool` (kept as own entity for future per-attachment overrides : required flag, parameter aliasing, max-call budget).
-- **HandlerKey** decouples definition from C# class name (handlers can be renamed without breaking the catalog).
-- When `IsActive = false`, the orchestrator skips the tool even if a skill still references it.
-**DO / DON'T:**
-- DO author tool descriptions for the model — short, action-oriented, with preconditions
-- DO snake_case the `Name` (LLM convention)
-- DON'T expose long-running or heavy tools via function calling — prefer Workflow steps
-- DON'T duplicate tool logic across skills — attach the same `AiTool` via `AiSkillTool`
-### AiAgentExecution — runtime tracking
-Each execution of an `AiAgent` is recorded via `AiAgentExecution` with:
-- `Status` : `Running` / `Completed` / `Failed` / `PartiallyCompleted` / `Cancelled`
-- `ExecutedSteps` / `TotalSteps`
-- `InputStateJson` / `FinalStateJson` (audit trail)
-- **Usage tracking** : `TotalInputTokens`, `TotalOutputTokens`, `TotalCost` (decimal), `TotalExecutionTimeMs`
-- `_stepExecutions` : per-step `AiAgentStepExecution` (with own status, tokens, cost)
-Service methods : `IncrementExecutedSteps()`, `MarkCompleted(json)`, `MarkFailed(msg)`, `MarkPartiallyCompleted(json, msg)`, `MarkCancelled(msg)`, `AccumulateUsage(in, out, cost, ms)`, `AddStepExecution(step)`.
-**Use** : surface in admin UI (run history, cost dashboard, debug trace). Each agent run produces one `AiAgentExecution` + N `AiAgentStepExecution`.
-### AI Evaluation Framework (R10)
-For benchmarking skills against expected outputs, see [references/eval-framework.md](references/eval-framework.md). Pattern: `AiEvalDataset` (test cases) + `AiEvaluation` (one run) + `AiEvalResult` (per-item outcome). Provider/model agnostic — same dataset can compare 2 versions of the same skill code.
-## Implementation
-Start with [steps/step-00-init.md](steps/step-00-init.md) to gather requirements, then proceed to [steps/step-01-implementation.md](steps/step-01-implementation.md) for:
-- Workflow steps (define use case, create prompt, define schema, execute)
-- AI service interfaces (IAiCompletionService, IPromptService)
-- Frontend integration (API, hooks, components)
-- Advanced patterns (streaming, fallback provider)
-## Checklist
-```
-- Prompt created (unique Code, Blocks, Variables, Version)
-- OutputSchema if structured response
-- Service with IAiCompletionService injected
-- Error handling + Logging (tokens, time)
-- Frontend: Hook/component, Loading, Error handling
-- ProviderInstance with budget limit
-- Tests: execution, variables, schema validation
-```
-## Absolute Rules
-| DO | DON'T |
-|----|-------|
-| IAiCompletionService for executions | Direct API calls |
-| OutputSchema for structured responses | Unvalidated responses |
-| Error handling (API down, quota) | Ignore token limits |
-| Log executions (tokens, duration) | Hardcode API keys |
-| Variables for dynamic content | Expose system prompts to frontend |
-## Key Files
-| File | Role |
-|------|------|
-| `Domain/AI/Prompts/Prompt.cs` | Prompt entity |
-| `Domain/AI/Schemas/OutputSchema.cs` | Schema validation |
-| `Domain/AI/AiProviderInstance.cs` | Configured instance |
-| `Domain/AI/Agents/AiAgent.cs` | Multi-step agent (R17 — v3.46+) |
-| `Domain/AI/Agents/AiAgentStep.cs` | Agent step with `Role` (Worker/Planner/Reasoner/Critic/Synthesizer) |
-| `Domain/AI/Agents/AiAgentExecution.cs` | Run tracking (status, tokens, cost, step executions) |
-| `Domain/AI/Skills/AiSkill.cs` | Reusable skill (`CacheTtlSeconds` for cache hint) |
-| `Domain/AI/Tools/AiTool.cs` | Function-calling tool (R2 — v3.46+) |
-| `Domain/AI/Tools/AiSkillTool.cs` | Many-to-many AiSkill ↔ AiTool |
-| `Domain/AI/Evaluations/AiEvalDataset.cs` | Eval dataset (R10 — v3.46+) |
-| `Domain/AI/Evaluations/AiEvaluation.cs` | Eval run with rollup stats |
-| `Application/Common/Interfaces/IAiCompletionService.cs` | Service interface |
-| `Application/Common/Interfaces/IToolHandler.cs` | Tool handler interface (resolved via HandlerKey) |
-| `Infrastructure/Services/AI/AiCompletionService.cs` | Implementation |
-| `web/src/services/api/aiApi.ts` | Frontend API |
-<success_criteria>
-- Prompt entity created with OutputSchema validation
-- IAiCompletionService integration wired correctly
-- Error handling for API failures and quota limits implemented
-- Token usage logged per execution
-</success_criteria>

package/templates/skills/ai-prompt/references/ai-agent-modes.md DELETED Viewed

@@ -1,89 +0,0 @@
-# AI Agent Modes & Step Roles (R17 — v3.46)
-> **Reference for `ai-prompt` skill** — how to choose `AiAgentMode` and `AiAgentStepRole` when scaffolding multi-step AI agents.
-## When This Reference Applies
-- You create an `AiAgent` with more than one step
-- You need a non-Sequential reasoning mode (loop, plan-then-execute, self-correct)
-- The user asks "how do I make the agent retry", "how do I make it plan first", "what is ReAct"
-For single-prompt skills, the basic `Prompt + Block + OutputSchema` pattern is enough — no agent, no mode.
----
-## `AiAgentMode` (4 values)
-| Mode | Value | Use case | Latency | Cost |
-|---|---|---|---|---|
-| `Sequential` | 0 | Known DAG fan-out / fan-in (analyze → summarize → email) | Low | Low |
-| `ReAct` | 1 | Reasoning + tool loop, plan unknown ahead of time | High | High |
-| `PlanAndExecute` | 2 | Task that can be planned upfront then executed | Medium | Medium |
-| `SelfCorrection` | 3 | Output that can be critiqued and replayed | Medium | Medium-High |
-### Recommended configuration
-| Field | Default | Range |
-|---|---|---|
-| `MaxIterations` | 5 | [1..20] — protects against infinite loops |
-| `QualityThreshold` | 0.8 | [0..1] — used by `SelfCorrection` to decide replay |
----
-## `AiAgentStepRole` (5 values)
-| Role | Value | Expected output schema |
-|---|---|---|
-| `Worker` | 0 | Standard skill output (used in `Sequential` mode) |
-| `Planner` | 1 | `{ plan: [{ skillCode, label }] }` — produces the plan in `PlanAndExecute` |
-| `Reasoner` | 2 | `{ action, input }` or `{ final_answer }` — used in `ReAct` |
-| `Critic` | 3 | `{ score: 0..1, feedback?: string }` — used in `SelfCorrection` |
-| `Synthesizer` | 4 | Final aggregated output (`PlanAndExecute` after parallel workers) |
----
-## Cache hint (R-cache)
-| Field | Type | Purpose |
-|---|---|---|
-| `AiSkill.CacheTtlSeconds` | `int?` | TTL for caching this skill's output (per input hash). Null = no cache. |
-| `AiSkillBlock.IsCacheable` | `bool` | Marks an idempotent block whose output can be reused across executions. |
-Only mark a skill / block cacheable when the output is **deterministic for a given input** — otherwise stale answers will be served.
----
-## Choosing a mode (decision tree)
-```
-Question: do I know the steps in advance?
-  Yes → Sequential
-  No  → Question: can the LLM decide the steps once, then execute?
-          Yes → PlanAndExecute
-          No  → Question: must I let the LLM iterate with tools?
-                  Yes → ReAct
-                  No  → SelfCorrection (single attempt + critique loop)
-```
----
-## DO / DON'T
-| ✅ DO | ❌ DON'T |
-|---|---|
-| Start with `Sequential` — switch to other modes only when needed | Default to `ReAct` (expensive, hard to debug) |
-| Cap `MaxIterations` at the smallest number that satisfies your case | Leave the default 5 for `ReAct` on long-running tasks (set 10-15) |
-| Set `QualityThreshold` based on prompt evaluation results | Pick `0.8` blindly — measure on your eval dataset |
-| Use `Critic` role with a structured output schema | Let the critic return free-form text |
-| Cache only deterministic, idempotent skills | Cache anything that uses `now()` or randomness |
----
-## Reference source files (read-only)
-- `D:\01 - projets\SmartStack.app\features\IA-Workflow\src\SmartStack.Domain\AI\Agents\AiAgent.cs`
-- `D:\01 - projets\SmartStack.app\features\IA-Workflow\src\SmartStack.Domain\AI\Agents\AiAgentMode.cs`
-- `D:\01 - projets\SmartStack.app\features\IA-Workflow\src\SmartStack.Domain\AI\Agents\AiAgentStep.cs`
-- `D:\01 - projets\SmartStack.app\features\IA-Workflow\src\SmartStack.Domain\AI\Agents\AiAgentStepRole.cs`
-- `D:\01 - projets\SmartStack.app\features\IA-Workflow\src\SmartStack.Domain\AI\Skills\AiSkill.cs` (CacheTtlSeconds)
-- `D:\01 - projets\SmartStack.app\features\IA-Workflow\src\SmartStack.Domain\AI\Skills\AiSkillBlock.cs` (IsCacheable)

package/templates/skills/ai-prompt/references/eval-framework.md DELETED Viewed

@@ -1,129 +0,0 @@
-# AI Evaluation Framework (R10 — v3.46+)
-> **Reference for `ai-prompt` skill** — how to evaluate AI skills against expected outputs.
-## When This Reference Applies
-- You are about to ship a new prompt or change an existing one
-- You need to compare two versions of the same skill (`v1.0.0` vs `v1.1.0`)
-- You want to benchmark the same prompt across providers/models (OpenAI vs Claude vs Gemini)
-- The user asks "how do I test my prompt", "how do I prevent regression", "how do I A/B prompts"
-For one-shot manual testing during development, the eval framework is overkill — call the skill directly. Use this framework when you want **reproducible, scored, auditable** runs.
----
-## The 4 entities
-### `AiEvalDataset` — collection of test cases
-```csharp
-class AiEvalDataset : BaseEntity, IAuditableEntity
-{
-    public string Code { get; }                  // kebab-case stable id, e.g. "support-classification-v1"
-    public string Name { get; }
-    public string? Description { get; }
-    public IReadOnlyCollection<AiEvalDatasetItem> Items { get; }
-}
-```
-**Provider/model agnostic** : the same dataset can be replayed against multiple skills, providers and models to compare quality and cost.
-### `AiEvalDatasetItem` — one test case
-```csharp
-class AiEvalDatasetItem
-{
-    public Guid DatasetId { get; }
-    public string Label { get; }                 // Human-readable name for the case
-    public string VariablesJson { get; }         // Inputs to feed into the skill
-    public string ExpectedOutputJson { get; }    // Expected result (for grading)
-}
-```
-### `AiEvaluation` — one run
-```csharp
-class AiEvaluation : BaseEntity, IAuditableEntity
-{
-    public Guid SkillId { get; }                 // Which skill was tested
-    public Guid DatasetId { get; }               // Which dataset was replayed
-    public AiEvaluationStatus Status { get; }    // Running / Completed / Failed
-    public DateTime StartedAt { get; }
-    public DateTime? CompletedAt { get; }
-    public int ProcessedItems { get; }
-    public int TotalItems { get; }
-    public int PassedItems { get; }              // Items whose actual output matched expected
-    public double? AverageScore { get; }         // [0..1], null while in progress
-    public IReadOnlyCollection<AiEvalResult> Results { get; }
-}
-enum AiEvaluationStatus { Running = 0, Completed = 1, Failed = 2 }
-```
-Service methods : `RecordResult(AiEvalResult)`, `MarkCompleted()`, `MarkFailed(reason)`. The aggregate computes `AverageScore` from the per-item `Score` values when completed.
-### `AiEvalResult` — per-item outcome
-Records actual output vs expected, the score (0..1), pass/fail flag, and any tokens/cost incurred.
----
-## Workflow
-```
-1. Curate dataset
-   └─ AiEvalDataset.Create("support-classification-v1", "Support classification — 50 cases")
-      └─ AddItem("simple billing question", { "ticket": "..." }, { "category": "billing" })
-      └─ AddItem("urgent outage report",   { "ticket": "..." }, { "category": "incident" })
-      └─ … 48 more items
-2. Run evaluation against current skill version
-   └─ AiEvaluation.Create(skillId, datasetId, totalItems: 50)
-      └─ For each item: invoke skill, grade output, RecordResult(actual, expected, score)
-      └─ MarkCompleted()
-      └─ Stored AverageScore = 0.86 (43/50 passed)
-3. Iterate — change prompt / blocks / model
-   └─ New AiEvaluation against same dataset
-   └─ Compare AverageScore : 0.86 → 0.92 (+0.06)
-4. Decide
-   └─ If new score significantly higher : promote prompt version
-   └─ If equal or lower : revert
-```
----
-## DO / DON'T
-| ✅ DO | ❌ DON'T |
-|---|---|
-| Build datasets from real production examples (anonymised) | Use synthetic / hallucinated test cases as the only ones |
-| Stabilise dataset.Code — never rename, only add new datasets | Mutate dataset items after first run (compromises history) |
-| Grade with structured comparison (JSON match, key fields, semantic distance) | Grade with substring search / regex |
-| Track cost per evaluation — reject prompt changes that 3× cost for marginal score | Optimise for score alone |
-| Run evals as part of the prompt-change PR review | Ship prompt changes without an eval baseline |
-| Keep `AverageScore` as the single headline metric | Multiply scoring criteria — pick one and stick to it |
----
-## Wiring into a release pipeline
-A prompt change should run the relevant evaluation as part of CI:
-1. PR opens with a new prompt version (`v1.1.0`).
-2. CI invokes a Command that creates an `AiEvaluation(skillId, datasetId, totalItems)` against `v1.1.0`.
-3. CI compares `AverageScore` of `v1.1.0` vs the latest passing eval of `v1.0.0`.
-4. PR is annotated with the delta. Score regression > 5% → PR blocked.
----
-## Reference source files (read-only)
-- `D:\01 - projets\SmartStack.app\features\IA-Workflow\src\SmartStack.Domain\AI\Evaluations\AiEvalDataset.cs`
-- `D:\01 - projets\SmartStack.app\features\IA-Workflow\src\SmartStack.Domain\AI\Evaluations\AiEvalDatasetItem.cs`
-- `D:\01 - projets\SmartStack.app\features\IA-Workflow\src\SmartStack.Domain\AI\Evaluations\AiEvaluation.cs`
-- `D:\01 - projets\SmartStack.app\features\IA-Workflow\src\SmartStack.Domain\AI\Evaluations\AiEvalResult.cs`
-See also [ai-agent-modes.md](ai-agent-modes.md) for `MaxIterations` / `QualityThreshold` (used by `SelfCorrection` mode in conjunction with eval scores).

package/templates/skills/ai-prompt/steps/step-00-init.md DELETED Viewed

@@ -1,47 +0,0 @@
-# Step 0: Initialization
-## YOUR TASK
-Gather context about the AI integration requirements before implementation.
-## EXECUTION SEQUENCE
-### 1. Identify AI Use Case
-- What type of AI integration? (prompt execution, chat, content generation, validation, analysis)
-- What model/provider should be used? (Claude, GPT-4, GPT-4o, Gemini, local model)
-- What is the input schema? (user query, structured data, multiple parameters)
-- What is the expected output? (text, JSON, structured object, classification)
-### 2. Check Existing Patterns
-- Search existing `Application/Common/Interfaces/IAiCompletionService` usage
-- Identify reusable patterns: AiProviderInstance configuration, OutputSchema definitions
-- Check for existing Prompt entities with similar use cases
-- Review error handling patterns for API failures and quota limits
-### 3. Plan Implementation
-- Determine required files:
-  - Prompt entity and PromptBlock creation
-  - OutputSchema if structured response needed
-  - Service integration with IAiCompletionService
-  - Frontend API client and React hook
-- Identify dependencies:
-  - Which AI provider instance to use? (API keys, budget limits)
-  - Token budget and cost implications
-  - Error handling strategy (fallback provider, graceful degradation)
-- Map variables and placeholders for dynamic content
-### 4. Define Success Criteria
-- Prompt executes with correct model and parameters
-- Response validates against OutputSchema (if applicable)
-- Token usage logged and budget respected
-- Error handling covers API downtime and quota exhaustion
-- Frontend integrates with loading/error states
-## SUCCESS METRICS
-- AI use case clearly identified and documented
-- Implementation plan with all required files listed
-- Dependencies identified (provider instance, budget, error handling)
-- Decision on structured vs. unstructured response
-- Token budget and cost reviewed
-## NEXT STEP
-Proceed to `./step-01-implementation.md` to implement the Prompt, OutputSchema, Service integration, and Frontend components.

package/templates/skills/ai-prompt/steps/step-01-implementation.md DELETED Viewed

@@ -1,122 +0,0 @@
-# AI Prompt - Implementation Workflow
-## 1. Define the Use Case
-| Question | Impact |
-|----------|--------|
-| Content type? | Model choice |
-| Structured response? | OutputSchema |
-| Multi-language? | Language variables |
-| Budget limited? | ProviderInstance |
-| Real-time? | Streaming |
-## 2. Create the Prompt
-```csharp
-var promptId = await _promptService.CreatePromptAsync(new CreatePromptRequest
-{
-    Code = "ticket-analyzer",
-    Name = "Ticket Analyzer",
-    Blocks = new[] {
-        new CreateBlockRequest {
-            BlockType = PromptBlockType.System,
-            Content = "Instructions...",
-            IsRequired = true
-        },
-        new CreateBlockRequest {
-            BlockType = PromptBlockType.User,
-            Content = "Ticket: {{ticketTitle}}\nDescription: {{ticketDescription}}",
-            IsRequired = true
-        }
-    }
-});
-```
-## 3. Define OutputSchema (if structured response)
-```csharp
-var schemaId = await _schemaService.CreateAsync(new CreateSchemaRequest
-{
-    Code = "ticket-analysis-result",
-    JsonSchema = @"{ ""type"": ""object"", ""required"": [""category"", ""priority""], ... }",
-    DotNetType = "SmartStack.Application.AI.TicketAnalysisResult"
-});
-```
-## 4. Execute the Prompt
-```csharp
-// Simple execution
-var result = await _aiService.ExecutePromptAsync(promptId, new Dictionary<string, object>
-{
-    ["ticketTitle"] = ticket.Title,
-    ["ticketDescription"] = ticket.Description
-});
-// With typed validation
-var typedResult = await _aiService.ExecutePromptWithValidationAsync<TicketAnalysisResult>(
-    promptId, variables);
-if (typedResult.Success && typedResult.IsValid) { /* use typedResult.Data */ }
-```
-## AI Services
-### IAiCompletionService
-```csharp
-Task<AiCompletionResult> CompleteAsync(AiCompletionRequest request, CancellationToken ct);
-Task<AiCompletionResult> ExecutePromptAsync(Guid promptId, Dictionary<string, object>? variables, ...);
-Task<AiValidatedCompletionResult<T>> ExecutePromptWithValidationAsync<T>(Guid promptId, ...);
-Task<AiValidatedCompletionResult<T>> ExecutePromptByCodeWithValidationAsync<T>(string promptCode, ...);
-```
-### IPromptService
-```csharp
-Task<PromptDto> GetPromptByCodeAsync(string code, string? version = null);
-Task<string> RenderPromptAsync(string code, Dictionary<string, object>? variables);
-Task<Guid> CreatePromptAsync(CreatePromptRequest request);
-Task ActivatePromptAsync(Guid promptId);
-// Block management: AddBlockToPromptAsync, UpdateBlockAsync, ReorderBlocksAsync
-```
-## Frontend Integration
-### API
-```typescript
-aiApi.getPrompts(status?, isTemplate?)
-aiApi.executePrompt(promptId, variables)
-aiApi.previewPrompt(promptId, variables)
-aiApi.getProviders() / aiApi.getModels(providerId?)
-aiApi.getSchemas() / aiApi.createSchema(data)
-```
-### Hook useAiCompletion
-```typescript
-const { execute, loading, error, result } = useAiCompletion<T>(promptCode);
-const data = await execute(variables);
-```
-### Component AiAssistantButton
-```tsx
-<AiAssistantButton
-  promptCode="ticket-analyzer"
-  variables={{ ticketTitle, ticketDescription }}
-  onResult={(result) => handleAnalysis(result)}
-  label="Analyze with AI"
-/>
-```
-## Advanced Patterns
-### Streaming Response
-```typescript
-const reader = response.body?.getReader();
-while (true) { const { done, value } = await reader.read(); if (done) break; /* append chunk */ }
-```
-### Fallback Provider
-```csharp
-foreach (var provider in providers.OrderBy(p => p.Priority)) {
-    var result = await _aiService.ExecutePromptAsync(promptId, variables, providerId: provider.Id);
-    if (result.Success) return result;
-}
-```