daily-journal-prompt/API_DOCUMENTATION.md

# Daily Journal Prompt Generator - API Documentation

## Overview

The Daily Journal Prompt Generator API provides endpoints for generating, managing, and interacting with AI-powered journal writing prompts. The API is built with FastAPI and provides automatic OpenAPI documentation.

## Base URL

- Development: `http://localhost:8000`
- Production: `https://your-domain.com`

## API Version

All endpoints are prefixed with `/api/v1`

## Authentication

Currently, the API does not require authentication as it's designed for single-user use. Future versions may add authentication for multi-user support.

## Error Handling

All endpoints return appropriate HTTP status codes:

- `200`: Success
- `400`: Bad Request (validation errors)
- `404`: Resource Not Found
- `422`: Unprocessable Entity (request validation failed)
- `500`: Internal Server Error

Error responses follow this format:
```json
{
  "error": {
    "type": "ErrorType",
    "message": "Human-readable error message",
    "details": {}, // Optional additional details
    "status_code": 400
  }
}
```

## Endpoints

### Prompt Operations

#### 1. Draw Prompts from Pool
**GET** `/api/v1/prompts/draw`

Draw prompts from the existing pool without making API calls.

**Query Parameters:**
- `count` (optional, integer): Number of prompts to draw (default: 6)

**Response:**
```json
{
  "prompts": [
    "Write about a time when...",
    "Imagine you could..."
  ],
  "count": 2,
  "remaining_in_pool": 18
}
```

#### 2. Fill Prompt Pool
**POST** `/api/v1/prompts/fill-pool`

Fill the prompt pool to target volume using AI.

**Response:**
```json
{
  "added": 5,
  "total_in_pool": 20,
  "target_volume": 20
}
```

#### 3. Get Pool Statistics
**GET** `/api/v1/prompts/stats`

Get statistics about the prompt pool.

**Response:**
```json
{
  "total_prompts": 15,
  "prompts_per_session": 6,
  "target_pool_size": 20,
  "available_sessions": 2,
  "needs_refill": true
}
```

#### 4. Get History Statistics
**GET** `/api/v1/prompts/history/stats`

Get statistics about prompt history.

**Response:**
```json
{
  "total_prompts": 8,
  "history_capacity": 60,
  "available_slots": 52,
  "is_full": false
}
```

#### 5. Get Prompt History
**GET** `/api/v1/prompts/history`

Get prompt history with optional limit.

**Query Parameters:**
- `limit` (optional, integer): Maximum number of history items to return

**Response:**
```json
[
  {
    "key": "prompt00",
    "text": "Most recent prompt text...",
    "position": 0
  },
  {
    "key": "prompt01",
    "text": "Previous prompt text...",
    "position": 1
  }
]
```

#### 6. Select Prompt (Add to History)
**POST** `/api/v1/prompts/select/{prompt_index}`

Select a prompt from drawn prompts to add to history.

**Path Parameters:**
- `prompt_index` (integer): Index of the prompt to select (0-based)

**Note:** This endpoint requires session management and is not fully implemented in the initial version.

### Feedback Operations

#### 7. Generate Theme Feedback Words
**GET** `/api/v1/feedback/generate`

Generate 6 theme feedback words using AI based on historic prompts.

**Response:**
```json
{
  "theme_words": ["creativity", "reflection", "growth", "memory", "imagination", "emotion"],
  "count": 6
}
```

#### 8. Rate Feedback Words
**POST** `/api/v1/feedback/rate`

Rate feedback words and update feedback system.

**Request Body:**
```json
{
  "ratings": {
    "creativity": 5,
    "reflection": 6,
    "growth": 4,
    "memory": 3,
    "imagination": 5,
    "emotion": 4
  }
}
```

**Response:**
```json
{
  "feedback_words": [
    {
      "key": "feedback00",
      "word": "creativity",
      "weight": 5
    },
    // ... 5 more items
  ],
  "added_to_history": true
}
```

#### 9. Get Current Feedback Words
**GET** `/api/v1/feedback/current`

Get current feedback words with weights.

**Response:**
```json
[
  {
    "key": "feedback00",
    "word": "creativity",
    "weight": 5
  }
]
```

#### 10. Get Feedback History
**GET** `/api/v1/feedback/history`

Get feedback word history.

**Response:**
```json
[
  {
    "key": "feedback00",
    "word": "creativity"
  }
]
```

## Data Models

### PromptResponse
```json
{
  "key": "string",      // e.g., "prompt00"
  "text": "string",     // Prompt text content
  "position": "integer" // Position in history (0 = most recent)
}
```

### PoolStatsResponse
```json
{
  "total_prompts": "integer",
  "prompts_per_session": "integer",
  "target_pool_size": "integer",
  "available_sessions": "integer",
  "needs_refill": "boolean"
}
```

### HistoryStatsResponse
```json
{
  "total_prompts": "integer",
  "history_capacity": "integer",
  "available_slots": "integer",
  "is_full": "boolean"
}
```

### FeedbackWord
```json
{
  "key": "string",    // e.g., "feedback00"
  "word": "string",   // Feedback word
  "weight": "integer" // Weight from 0-6
}
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `DEEPSEEK_API_KEY` | DeepSeek API key | (required) |
| `OPENAI_API_KEY` | OpenAI API key | (optional) |
| `API_BASE_URL` | API base URL | `https://api.deepseek.com` |
| `MODEL` | AI model to use | `deepseek-chat` |
| `DEBUG` | Debug mode | `false` |
| `ENVIRONMENT` | Environment | `development` |
| `HOST` | Server host | `0.0.0.0` |
| `PORT` | Server port | `8000` |
| `MIN_PROMPT_LENGTH` | Minimum prompt length | `500` |
| `MAX_PROMPT_LENGTH` | Maximum prompt length | `1000` |
| `NUM_PROMPTS_PER_SESSION` | Prompts per session | `6` |
| `CACHED_POOL_VOLUME` | Target pool size | `20` |
| `HISTORY_BUFFER_SIZE` | History capacity | `60` |
| `FEEDBACK_HISTORY_SIZE` | Feedback history capacity | `30` |

### File Structure

```
data/
├── prompts_historic.json    # Historic prompts (cyclic buffer)
├── prompts_pool.json        # Prompt pool
├── feedback_words.json      # Current feedback words with weights
├── feedback_historic.json   # Historic feedback words
├── ds_prompt.txt           # Prompt generation template
├── ds_feedback.txt         # Feedback analysis template
└── settings.cfg            # Application settings
```

## Running the API

### Development
```bash
cd backend
uvicorn main:app --reload
```

### Production
```bash
cd backend
uvicorn main:app --host 0.0.0.0 --port 8000
```

### Docker
```bash
docker-compose up --build
```

## Interactive Documentation

FastAPI provides automatic interactive documentation:

- Swagger UI: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`

## Rate Limiting

Currently, the API does not implement rate limiting. Consider implementing rate limiting in production if needed.

## CORS

CORS is configured to allow requests from:
- `http://localhost:3000` (frontend dev server)
- `http://localhost:80` (frontend production)

Additional origins can be configured via the `BACKEND_CORS_ORIGINS` environment variable.

## Health Check

**GET** `/health`

Returns:
```json
{
  "status": "healthy",
  "service": "daily-journal-prompt-api"
}
```

## Root Endpoint

**GET** `/`

Returns API information:
```json
{
  "name": "Daily Journal Prompt Generator API",
  "version": "1.0.0",
  "description": "API for generating and managing journal writing prompts",
  "docs": "/docs",
  "health": "/health"
}
```

## Future Enhancements

1. **Authentication**: Add JWT or session-based authentication
2. **Rate Limiting**: Implement request rate limiting
3. **WebSocket Support**: Real-time prompt generation updates
4. **Export Functionality**: Export prompts to PDF/Markdown
5. **Prompt Customization**: User-defined prompt templates
6. **Multi-language Support**: Generate prompts in different languages
7. **Analytics**: Track prompt usage and user engagement
8. **Social Features**: Share prompts, community prompts