---
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>
