mistral-reference-architecture
Implement Mistral AI reference architecture with best-practice project layout. Use when designing new Mistral AI integrations, reviewing project structure, or establishing architecture standards for Mistral AI applications. Trigger with phrases like "mistral architecture", "mistral best practices", "mistral project structure", "how to organize mistral", "mistral layout".
- License 许可
- MIT
- 最近更新
- 2026-05-26
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- mistral-reference-architecture
- author
- Jeremy Longshore <jeremy@intentsolutions.io>
- license
- MIT
- version
- 1.0.0
- description
- Implement Mistral AI reference architecture with best-practice project layout. Use when designing new Mistral AI integrations, reviewing project structure, or establishing architecture standards for Mistral AI applications. Trigger with phrases like "mistral architecture", "mistral best practices", "mistral project structure", "how to organize mistral", "mistral layout".
- allowed-tools
- Read, Grep
- compatible-with
- claude-code, codex, openclaw
02 资源文件 1
- 参考文档references/implementation.md2.8 KB
03 SKILL.md 正文
Mistral AI Reference Architecture
Table of Contents
Overview
Production-ready architecture patterns for Mistral AI integrations. Covers layered project structure, client singleton, configuration management, error handling, service layer with caching, health checks, and prompt templates.
Prerequisites
- Understanding of layered architecture
- Mistral AI SDK knowledge
- TypeScript project setup
- Testing framework configured
Layer Architecture
API Layer (Routes, Controllers, Middleware)
↓
Service Layer (Business Logic, Orchestration)
↓
Mistral Layer (Client, Prompts, Error Handling)
↓
Infrastructure Layer (Cache, Queue, Monitoring)
Instructions
Step 1: Create Directory Structure
Organize into src/mistral/ (client, config, types, errors, prompts, handlers), src/services/ai/ (chat, rag, cache), src/api/ (routes, streaming), tests/ (unit, integration), and config/ (per-environment JSON).
Step 2: Implement Client Singleton
Create getMistralClient() factory that lazily initializes a single Mistral instance with config from environment. Include resetMistralClient() for testing.
Step 3: Configure with Zod Validation
Define config schema with z.object() for apiKey, model (default mistral-small-latest), timeout (30s), maxRetries (3), and cache settings. Parse from environment variables.
Step 4: Build Error Handling Layer
Create MistralServiceError class with code, status, retryable flag. Wrap raw errors: 429 = RATE_LIMIT (retryable), 401 = AUTH_ERROR, 500+ = SERVICE_ERROR (retryable).
Step 5: Implement Service Layer
Build ChatService with complete() and stream() methods. Add cache check for deterministic requests (temperature=0). Wrap all calls with retry and error handling.
Step 6: Add Health Check
Implement checkMistralHealth() that calls client.models.list() and returns status (healthy/degraded/unhealthy) with latency measurement.
Step 7: Create Prompt Templates
Define reusable PromptTemplate interface with system prompt and user template function. Include templates for summarize, classify, and codeReview.
Output
- Structured project layout with clear layer separation
- Client singleton wrapper with retry logic
- Zod-validated configuration management
- Custom error classes with retryable detection
- Service layer with caching and streaming
- Health check endpoint
- Reusable prompt templates
Error Handling
| Issue | Cause | Resolution |
|---|---|---|
| Rate limit (429) | Too many requests | Retry with backoff, marked retryable |
| Auth error (401) | Invalid API key | Check credentials, not retryable |
| Server error (5xx) | Mistral service issue | Retry with backoff, marked retryable |
| Config validation | Missing/invalid env vars | Check Zod schema errors |
Examples
Client Usage
const client = getMistralClient();
const response = await client.chat.complete({
model: 'mistral-small-latest',
messages: [{ role: 'user', content: 'Hello' }],
});
See detailed implementation for advanced patterns.
Resources
04 同仓库更多 Skills
zustand-store-ts
Create Zustand stores with TypeScript, subscribeWithSelector middleware, and proper state/action separation. Use when building React state management, creating global stores, or implementing reactive state patterns with Zustand.
zustand-store-creator
Zustand Store Creator - Auto-activating skill for Frontend Development. Triggers on: zustand store creator, zustand store creator Part of the Frontend Development skill category.
zero-trust-config-helper
Zero Trust Config Helper - Auto-activating skill for Security Advanced. Triggers on: zero trust config helper, zero trust config helper Part of the Security Advanced skill category.
zapier-integration-helper
Zapier Integration Helper - Auto-activating skill for Business Automation. Triggers on: zapier integration helper, zapier integration helper Part of the Business Automation skill category.
zai-cli
Execute z.AI CLI providing vision, search, reader, and GitHub exploration via CLI and MCP. Use when user needs image/video analysis, OCR, UI-to-code conversion, error diagnosis, real-time web search, web page to markdown extraction, or GitHub code exploration. Trigger with phrases like "analyze this image", "search the web for", "read this page", "explore this repo", or "use zai". Requires Z_AI_API_KEY.
yt-research
Research competitor YouTube channels, niches, and trending topics for your content strategy. Use this skill whenever the user says "research channels", "analyze competitors", "find trending topics", "niche analysis", "competitive research", "what are other creators doing", "scrape YouTube channels", or wants to understand the competitive landscape for a specific tool or topic area. Use when working with yt research. Trigger with 'yt', 'research'.