docs/python-ai-service-contract.md

# Python AI service contract

## Endpoint

```http
POST /ai/analyze-post
```

## Request

```json
{
  "postId": 101,
  "content": "Hom nay hoc Spring Boot Kafka kha hay"
}
```

## Response

```json
{
  "postId": 101,
  "modelName": "sentence-transformers/all-MiniLM-L6-v2",
  "dimension": 384,
  "embedding": [0.012, -0.034, 0.221],
  "moderation": {
    "status": "SAFE",
    "spamScore": 0.05,
    "toxicityScore": 0.01,
    "scamScore": 0.02
  }
}
```

## Responsibilities

Python should:

1. Receive `postId` and `content`.
2. Clean text lightly.
3. Generate embedding with `sentence-transformers/all-MiniLM-L6-v2`.
4. Calculate spam, toxicity, and scam scores.
5. Return the response above.

Python should not return or calculate:

- topic
- hashtag
- keyword
- summary

## Moderation Status

Allowed values:

- `SAFE`
- `LIMITED`
- `BLOCKED`

Scores should be normalized from `0.0` to `1.0`.

Spring Boot derives `qualityScore` from moderation scores:

```text
qualityScore = 1 - (spamScore * 0.4 + toxicityScore * 0.4 + scamScore * 0.2)
```

The value is clamped to `0.0..1.0`.

## Minimal FastAPI Shape

```python
from fastapi import FastAPI
from pydantic import BaseModel
from sentence_transformers import SentenceTransformer

app = FastAPI()
model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")

class AnalyzePostRequest(BaseModel):
    postId: int
    content: str

@app.post("/ai/analyze-post")
def analyze_post(request: AnalyzePostRequest):
    content = " ".join((request.content or "").split())
    embedding = model.encode(content).tolist()
    return {
        "postId": request.postId,
        "modelName": "sentence-transformers/all-MiniLM-L6-v2",
        "dimension": len(embedding),
        "embedding": embedding,
        "moderation": {
            "status": "SAFE",
            "spamScore": 0.0,
            "toxicityScore": 0.0,
            "scamScore": 0.0,
        },
    }
```