docs/python-ai-service-contract.md

Python AI service contract

Endpoint

POST /ai/analyze-post

Request

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

Response

{
  "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:

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

The value is clamped to 0.0..1.0.

Minimal FastAPI Shape

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,
        },
    }