AI Prompts Library

Act as an LLM cost analyst. I will give you a description of an AI feature and its traffic. Produce a cost breakdown and a reduction plan.

Deliver:

1. CURRENT COST MODEL
   Per-request token estimate (input, cached, output), cost per request, monthly total. Show the arithmetic.

2. WHERE THE TOKENS GO
   Rank the biggest contributors: system prompt, retrieved context, conversation history, output length, retries.

3. REDUCTION LEVERS, RANKED BY SAVING PER UNIT OF EFFORT
   For each: estimated percentage saved, implementation effort, and what quality risk it carries.
   Consider at minimum: prompt caching, routing cheap requests to a smaller model, batch API, trimming the system prompt, retrieval instead of stuffing, capping output length, deduplicating retries.

4. THE ONE CHANGE TO MAKE FIRST
   Pick one. Justify it in two sentences.

Do not suggest anything that requires changing model provider unless the saving exceeds 40 percent.

Feature:
[DESCRIBE]
Traffic:
[REQUESTS PER DAY, AVERAGE SIZES]

Generate a REST API endpoint with the following spec:

Method: [GET / POST / PUT / DELETE]
Path: [/api/...]
Purpose: [WHAT IT DOES]
Auth: [JWT / API key / public]
Framework: [Express / FastAPI / Rails / Laravel]

Deliverables:
1. Route handler with input validation
2. OpenAPI/Swagger spec for this endpoint
3. TypeScript / Pydantic types for request and response
4. Two unit tests (happy path + invalid input)
5. cURL example for manual testing

Follow the existing project conventions for error handling, logging, and response shape.

You are a senior backend engineer specializing in Python FastAPI applications. Generate a complete, production-ready API module based on the requirements below.

**Module Requirements:**
- Resource name: [RESOURCE_NAME, e.g., 'users', 'products', 'orders']
- Database: [PostgreSQL/MongoDB/SQLite]
- ORM: [SQLAlchemy/Tortoise-ORM/Motor]
- Authentication: [JWT/OAuth2/API Key/None]
- Description: [WHAT_THIS_MODULE_DOES]

**Generate the following files:**

1. **models.py** - SQLAlchemy/Pydantic models:
   - Database model with proper column types, indexes, and constraints
   - Created_at, updated_at timestamps with timezone awareness
   - Soft delete support (is_deleted flag)
   - Relationship definitions

2. **schemas.py** - Pydantic v2 schemas:
   - CreateSchema (input validation for POST)
   - UpdateSchema (partial updates for PATCH, all fields Optional)
   - ResponseSchema (API output, excludes sensitive fields)
   - ListResponseSchema (paginated list with metadata)
   - Use Field() validators with examples in json_schema_extra

3. **router.py** - FastAPI router:
   - GET / - List with pagination, sorting, filtering
   - GET /{id} - Single resource with 404 handling
   - POST / - Create with 201 response and Location header
   - PATCH /{id} - Partial update
   - DELETE /{id} - Soft delete with 204 response
   - Include proper response_model, status_code, summary, description
   - Dependency injection for auth, database session

4. **service.py** - Business logic layer:
   - CRUD operations separated from route handlers
   - Transaction management
   - Custom exception classes
   - Event hooks (pre_create, post_create, etc.)

5. **tests/test_[resource].py** - Pytest tests:
   - Test each endpoint with valid and invalid data
   - Test authentication and authorization
   - Test edge cases (duplicate, not found, validation errors)
   - Use pytest fixtures and httpx AsyncClient

All code must include type hints, docstrings, and follow PEP 8.

You are an API design expert. Generate a complete OpenAPI 3.1 specification for the described API.

**API Details:**
- API Name: [API_NAME]
- Base URL: [BASE_URL]
- Version: [VERSION]
- Description: [WHAT_THE_API_DOES]
- Authentication: [Bearer JWT / API Key / OAuth2 / None]
- Resources: [LIST_YOUR_RESOURCES, e.g., users, products, orders]

**For each resource, generate:**

1. **Paths**: All CRUD endpoints plus any custom actions
   - Proper HTTP methods (GET, POST, PUT, PATCH, DELETE)
   - Path parameters with descriptions
   - Query parameters for filtering, pagination, sorting
   - Request bodies with required/optional fields
   - All possible response codes (200, 201, 204, 400, 401, 403, 404, 409, 422, 500)

2. **Schemas** (components/schemas):
   - Request schemas (Create, Update with partial fields)
   - Response schemas (single item, paginated list)
   - Error schema with code, message, details array
   - Enum types for status fields
   - Proper use of allOf, oneOf, anyOf for schema composition

3. **Security Schemes**: Define authentication with examples

4. **Tags**: Group endpoints logically with descriptions

5. **Examples**: Provide realistic request/response examples for every endpoint

6. **Pagination**: Use cursor-based or offset pagination with Link headers

7. **Rate Limiting**: Document rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining)

**Output Format:** Valid YAML OpenAPI 3.1 specification that can be imported directly into Swagger UI, Postman, or any OpenAPI-compatible tool. Include inline comments explaining design decisions.

You are a developer relations writer who creates clear, developer-friendly API changelogs. Write a changelog entry based on the described changes.

**API Name:** [API_NAME]
**Version:** [FROM_VERSION -> TO_VERSION]
**Release Date:** [DATE]
**Changes:** [DESCRIBE ALL CHANGES - new endpoints, modified behavior, deprecations, bug fixes]

**Changelog Format:**

1. **Header:**
   - Version number and date
   - Release type badge: Major (breaking) / Minor (features) / Patch (fixes)
   - One-sentence summary of the most important change

2. **Breaking Changes** (if any):
   - Use a prominent warning callout
   - Describe exactly what changed and what breaks
   - Provide migration code examples (before/after)
   - Include a migration deadline if applicable
   - Link to migration guide

3. **New Features:**
   - New endpoints with method, path, and brief description
   - New query parameters or request fields
   - New response fields
   - Include minimal working code examples
   - Link to full documentation

4. **Improvements:**
   - Performance improvements with metrics
   - Enhanced error messages
   - Expanded validation rules
   - New SDK support

5. **Bug Fixes:**
   - Brief description of what was wrong
   - What the correct behavior is now
   - Reference issue numbers if applicable

6. **Deprecations:**
   - What is deprecated and when it will be removed
   - Replacement/alternative to use instead
   - Code example showing the migration

7. **Known Issues:**
   - Any outstanding issues in this release
   - Workarounds if available

**Writing Rules:**
- Use present tense ("adds" not "added")
- Be specific ("response time reduced from 500ms to 120ms" not "improved performance")
- Always include code examples for breaking changes
- Use semantic versioning terminology correctly

**Output**: Changelog entry in Markdown format, ready to publish.

Generate comprehensive API documentation for [API NAME].

**API Details:**
- Base URL: [URL]
- Authentication: [TYPE]
- Version: [VERSION]

**For Each Endpoint:**

```yaml
/api/endpoint:
  method:
    summary: Brief description
    description: Detailed explanation
    parameters:
      - name: param
        in: query/path/header
        required: true/false
        schema:
          type: string/number/etc
        description: Parameter purpose
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              field: type
    responses:
      '200':
        description: Success response
        content:
          application/json:
            example:
              {data}
      '400':
        description: Error response
```

**Include:**
- Authentication guide
- Rate limiting info
- Error codes
- Code examples (cURL, JavaScript, Python)
- Changelog
- Postman collection

Webhook endpoint for [SERVICE A → SERVICE B]:

**Endpoint** - POST handler
**Signature Verification** - HMAC validation, timestamp check
**Payload Processing** - Validation, transformation, error handling
**Idempotency** - Prevent duplicate processing
**Retry Logic** - Exponential backoff
**Monitoring** - Logging, alerts, metrics

Include: Full code, tests, deployment.

Design comprehensive API error response:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Detailed explanation",
    "timestamp": "2025-10-02T02:00:00Z",
    "request_id": "uuid",
    "documentation_url": "https://docs.example.com/errors/ERROR_CODE",
    "field_errors": [
      {
        "field": "email",
        "message": "Invalid email format",
        "code": "INVALID_FORMAT"
      }
    ]
  }
}
```

**Error Categories**:
- 4xx Client Errors: Authentication, validation, not found
- 5xx Server Errors: Internal, service unavailable, timeout

**Best Practices**:
- Use consistent error codes
- Provide actionable messages
- Include request tracking
- Add documentation links
- Never expose sensitive data

You are a technical documentation specialist creating comprehensive, user-friendly documentation.

Project: [PROJECT NAME]
Audience: [TARGET USER LEVEL: Beginner/Intermediate/Advanced]
Technology Stack: [TECHNOLOGIES]

Create documentation that includes:

**1. Overview Section**
- Purpose and goals
- Key features
- Prerequisites
- Architecture diagram (describe in detail)

**2. Getting Started**
- Installation steps (OS-specific if needed)
- Initial configuration
- First-time setup
- Quick start example

**3. Core Concepts**
- Fundamental principles
- Terminology glossary
- Common patterns
- Best practices

**4. API Reference** (if applicable)
- Endpoint descriptions
- Parameters and types
- Request/response examples
- Error codes

**5. Advanced Topics**
- Performance optimization
- Troubleshooting guide
- FAQ section
- Migration guides

**6. Code Examples**
- Common use cases (with code)
- Integration examples
- Testing examples

Format: Use clear headings, code blocks, callouts for warnings/tips, and maintain consistent terminology.