@atlashub/smartstack-cli 3.39.0 → 3.41.0

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

@@ -1,107 +1,107 @@
----
-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-3-opus/sonnet/haiku, 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
-
-## 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 |
-| `Application/Common/Interfaces/IAiCompletionService.cs` | Service interface |
-| `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>
+---
+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
+
+## 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 |
+| `Application/Common/Interfaces/IAiCompletionService.cs` | Service interface |
+| `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/steps/step-00-init.md

@@ -1,47 +1,47 @@
-# 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.
+# 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

@@ -1,122 +1,122 @@
-# 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;
-}
-```
+# 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;
+}
+```