> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deepdiveplatform.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ML Enrichment

> Enhance your data with AI-powered analysis

Enhance your social media data with AI-powered analysis. ML enrichment can be applied to any content-fetching endpoint or used directly via the `/ml/analyze` endpoint.

## Available Enrichment Types

### Sentiment Analysis

Classify text as positive, negative, or neutral.

```json theme={null}
{
  "enrich": ["sentiment"]
}
```

**Response:**

```json theme={null}
{
  "enrichment": {
    "sentiment": "positive",
    "sentiment_score": 0.92
  }
}
```

### Topic Extraction

Identify main topics discussed in the text.

```json theme={null}
{
  "enrich": ["topics"]
}
```

**Response:**

```json theme={null}
{
  "enrichment": {
    "topics": ["technology", "innovation", "startups"]
  }
}
```

### Custom Topic Categories

Define your own topic categories for classification:

```json theme={null}
{
  "enrich": ["topics"],
  "categories": {
    "topic": ["product", "service", "pricing", "support", "feature_request"]
  }
}
```

**Response:**

```json theme={null}
{
  "enrichment": {
    "topics": ["product", "feature_request"]
  }
}
```

### Intent Detection

Identify the user's intent behind the text.

```json theme={null}
{
  "enrich": ["intent"]
}
```

**Response:**

```json theme={null}
{
  "enrichment": {
    "intent": "purchase_intent"
  }
}
```

Common intents include:

* `purchase_intent` - User wants to buy something
* `complaint` - User is expressing dissatisfaction
* `question` - User is asking for information
* `praise` - User is giving positive feedback
* `suggestion` - User is making a recommendation

### Keyword Extraction

Extract important keywords and phrases.

```json theme={null}
{
  "enrich": ["keywords"]
}
```

**Response:**

```json theme={null}
{
  "enrichment": {
    "keywords": ["machine learning", "AI", "automation", "efficiency"]
  }
}
```

## Combining Enrichments

Request multiple enrichment types in a single call:

```json theme={null}
{
  "username": "charlidamelio",
  "limit": 10,
  "enrich": ["sentiment", "topics", "intent", "keywords"]
}
```

**Response:**

```json theme={null}
{
  "enrichment": {
    "sentiment": "positive",
    "sentiment_score": 0.85,
    "topics": ["dance", "entertainment"],
    "intent": "engagement",
    "keywords": ["dance", "tutorial", "fyp", "trending"]
  }
}
```

## LLM Provider Selection

Choose which AI model to use for enrichment:

```json theme={null}
{
  "username": "charlidamelio",
  "limit": 10,
  "enrich": ["sentiment", "topics"],
  "llm_provider": "gemini-2.0-flash"
}
```

Available providers:

* `gemini-2.0-flash` (default) - Fast, cost-effective
* `gemini-1.5-pro` - More accurate, higher cost

## Direct ML Analysis

Use the `/ml/analyze` endpoint for standalone text analysis:

```bash theme={null}
curl -X POST "https://data-api.deepdiveplatform.com/api/v1/ml/analyze" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": [
      "I love this product! Best purchase ever!",
      "This is terrible. Want a refund.",
      "How do I contact support?"
    ],
    "analyses": ["sentiment", "intent"]
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "text": "I love this product! Best purchase ever!",
        "sentiment": "positive",
        "sentiment_score": 0.95,
        "intent": "praise"
      },
      {
        "text": "This is terrible. Want a refund.",
        "sentiment": "negative",
        "sentiment_score": 0.12,
        "intent": "complaint"
      },
      {
        "text": "How do I contact support?",
        "sentiment": "neutral",
        "sentiment_score": 0.48,
        "intent": "question"
      }
    ]
  },
  "metadata": {
    "credits_used": 6,
    "enrichments": ["sentiment", "intent"]
  }
}
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Batch your texts" icon="layer-group">
    The ML analyze endpoint supports up to 25 texts per request
  </Card>

  <Card title="Use custom categories" icon="tags">
    For better topic classification in your domain
  </Card>

  <Card title="Cache results" icon="database">
    ML analysis results are deterministic for the same input
  </Card>

  <Card title="Choose appropriate enrichments" icon="check">
    Only request what you need to save credits
  </Card>
</CardGroup>