Deploy contextual paraphrase refinements

.env.example

@@ -13,6 +13,14 @@ GROQ_API_KEY=
 HF_API_TOKEN=
 # HF_MODEL=mistralai/Mistral-7B-Instruct-v0.3
 
+# ── Premium tier ──────────────────────────────────────────────────────────────
+# GitHub Models (requires GitHub PAT with Models scope — free with Student Pack)
+# GITHUB_PAT=ghp_your_github_pat_here
+# GITHUB_MODEL=Meta-Llama-3.1-405B-Instruct
+
+# Promo codes that unlock premium (comma-separated)
+# PREMIUM_PROMO_CODES=LAUNCH2024,BETAUSER
+
 # ── Optional overrides ────────────────────────────────────────────────────────
 # Grammar: defaults to public languagetool.org API (free, no key needed)
 # Override to point at a self-hosted LanguageTool container

models/schemas.py

@@ -1,5 +1,5 @@
 from pydantic import BaseModel, Field
-from typing import Optional
+from typing import Literal, Optional
 
 
 # ── Paraphrase ──────────────────────────────────────────────────────────────
@@ -8,6 +8,10 @@ class ParaphraseRequest(BaseModel):
     text: str = Field(..., min_length=1, max_length=10000, description="Text to paraphrase")
     intensity: int = Field(3, ge=1, le=5, description="Paraphrase intensity (1=minimal, 5=aggressive)")
     model: str = Field("standard", description="Model to use: 'standard' or a GitHub Models model name")
+    writing_mode: Literal[
+        "standard", "fluency", "formal", "simple", "creative",
+        "academic", "expand", "shorten", "humanize",
+    ] = Field("standard", description="Writing style for the paraphrase")
 
 
 class ParaphraseResponse(BaseModel):
@@ -15,6 +19,25 @@ class ParaphraseResponse(BaseModel):
     paraphrased: str
     intensity: int
     model_used: str = "standard"
+    writing_mode: str = "standard"
+
+
+class ParaphraseRefineRequest(BaseModel):
+    text: str = Field(..., min_length=1, max_length=10000, description="Full paraphrased text for context")
+    selected_text: str = Field(..., min_length=1, max_length=2000, description="Selected sentence or word")
+    kind: Literal["sentence", "word"]
+    writing_mode: Literal[
+        "standard", "fluency", "formal", "simple", "creative",
+        "academic", "expand", "shorten", "humanize",
+    ] = "standard"
+    intensity: int = Field(3, ge=1, le=5)
+    count: int = Field(5, ge=2, le=8)
+
+
+class ParaphraseRefineResponse(BaseModel):
+    selected_text: str
+    kind: str
+    suggestions: list[str]
 
 
 # ── Grammar ─────────────────────────────────────────────────────────────────

routers/paraphrase.py

@@ -2,11 +2,17 @@ from fastapi import APIRouter, Depends, HTTPException
 from sqlalchemy.orm import Session
 
 from database import get_db
-from models.schemas import ParaphraseRequest, ParaphraseResponse
+from models.schemas import (
+    ParaphraseRefineRequest,
+    ParaphraseRefineResponse,
+    ParaphraseRequest,
+    ParaphraseResponse,
+)
 from routers.auth import _optional_user_id
 from services.auth_service import get_user_by_id
 from services.paraphrase_service import paraphrase as _paraphrase
 from services.paraphrase_service import paraphrase_premium as _paraphrase_premium
+from services.paraphrase_service import refine_selection as _refine_selection
 
 router = APIRouter(prefix="/api", tags=["paraphrase"])
 
@@ -34,9 +40,18 @@ def paraphrase_endpoint(
 
     try:
         if use_premium:
-            result_text, model_used = _paraphrase_premium(request.text, request.intensity, model=request.model)
+            result_text, model_used = _paraphrase_premium(
+                request.text,
+                request.intensity,
+                model=request.model,
+                writing_mode=request.writing_mode,
+            )
         else:
-            result_text, model_used = _paraphrase(request.text, request.intensity)
+            result_text, model_used = _paraphrase(
+                request.text,
+                request.intensity,
+                writing_mode=request.writing_mode,
+            )
     except Exception as exc:
         raise HTTPException(status_code=500, detail=str(exc))
 
@@ -45,4 +60,30 @@ def paraphrase_endpoint(
         paraphrased=result_text,
         intensity=request.intensity,
         model_used=model_used,
+        writing_mode=request.writing_mode,
+    )
+
+
+@router.post(
+    "/paraphrase/refine",
+    response_model=ParaphraseRefineResponse,
+    summary="Suggest contextual sentence or word alternatives",
+)
+def refine_paraphrase(request: ParaphraseRefineRequest) -> ParaphraseRefineResponse:
+    try:
+        suggestions = _refine_selection(
+            text=request.text,
+            selected_text=request.selected_text,
+            kind=request.kind,
+            writing_mode=request.writing_mode,
+            intensity=request.intensity,
+            count=request.count,
+        )
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc))
+
+    return ParaphraseRefineResponse(
+        selected_text=request.selected_text,
+        kind=request.kind,
+        suggestions=suggestions,
     )

services/paraphrase_service.py

@@ -15,6 +15,18 @@ logger = logging.getLogger(__name__)
 
 _CHUNK_CHAR_LIMIT = 3500
 
+MODE_PROMPTS: dict[str, str] = {
+    "standard": "Use natural vocabulary and varied sentence structure.",
+    "fluency": "Prioritize clarity, readability, grammar, and a smooth natural flow.",
+    "formal": "Use polished, professional language without sounding inflated.",
+    "simple": "Use plain language and shorter, easier-to-understand phrasing.",
+    "creative": "Use fresh, expressive phrasing while preserving every fact.",
+    "academic": "Use precise, objective, scholarly language and retain technical terms.",
+    "expand": "Add useful clarity and transitions, but do not invent facts or arguments.",
+    "shorten": "Make the text concise while preserving every essential fact and qualification.",
+    "humanize": "Use natural cadence, varied syntax, and idiomatic wording that sounds genuinely human.",
+}
+
 INTENSITY_PROMPTS: dict[int, str] = {
     1: (
         "Paraphrase the following text with minimal changes — only replace a few words "
@@ -41,25 +53,33 @@ INTENSITY_PROMPTS: dict[int, str] = {
 
 _SYSTEM_PROMPT = (
     "You are a professional writing assistant specialised in paraphrasing. "
+    "Preserve every fact, name, number, date, citation, technical term, and negation. "
+    "Never generalise a precise claim or add information that is not in the source. "
+    "Keep paragraph boundaries and, unless asked to expand or shorten, keep roughly the same length. "
     "Return ONLY the paraphrased text — no explanations, no labels, "
     "no quotation marks, no preamble."
 )
 
 
-def paraphrase(text: str, intensity: int = 3) -> tuple[str, str]:
+def paraphrase(text: str, intensity: int = 3, writing_mode: str = "standard") -> tuple[str, str]:
     """Return (paraphrased_text, model_used) at the given intensity (1-5)."""
     try:
-        return _paraphrase_llm(text, intensity), "standard"
+        return _paraphrase_llm(text, intensity, writing_mode), "standard"
     except RuntimeError:
         return _paraphrase_t5(text, intensity), "standard"
 
 
-def paraphrase_premium(text: str, intensity: int = 3, model: str = "Meta-Llama-3.1-405B-Instruct") -> tuple[str, str]:
+def paraphrase_premium(
+    text: str,
+    intensity: int = 3,
+    model: str = "Meta-Llama-3.1-405B-Instruct",
+    writing_mode: str = "standard",
+) -> tuple[str, str]:
     """Paraphrase using a premium GitHub Models model. Returns (text, model_used)."""
     try:
-        return _paraphrase_llm_premium(text, intensity, model)
+        return _paraphrase_llm_premium(text, intensity, model, writing_mode)
     except RuntimeError:
-        return _paraphrase_llm(text, intensity), "standard"
+        return _paraphrase_llm(text, intensity, writing_mode), "standard"
 
 
 def _split_into_chunks(text: str) -> list[str]:
@@ -84,9 +104,10 @@ def _split_into_chunks(text: str) -> list[str]:
     return chunks if chunks else [text]
 
 
-def _paraphrase_with_fn(text: str, intensity: int, chat_fn) -> str:
+def _paraphrase_with_fn(text: str, intensity: int, chat_fn, writing_mode: str = "standard") -> str:
     """Shared chunking logic for both free and premium paraphrasing."""
     instruction = INTENSITY_PROMPTS.get(intensity, INTENSITY_PROMPTS[3])
+    mode_instruction = MODE_PROMPTS.get(writing_mode, MODE_PROMPTS["standard"])
     chunks = _split_into_chunks(text)
 
     parts: list[str] = []
@@ -103,22 +124,32 @@ def _paraphrase_with_fn(text: str, intensity: int, chat_fn) -> str:
             )
         part = chat_fn(
             system_prompt=_SYSTEM_PROMPT,
-            user_prompt=f"{instruction}{context}\n\nText to paraphrase:\n{chunk}\n\nParaphrased version:",
+            user_prompt=(
+                f"{instruction} {mode_instruction}{context}\n\n"
+                f"Text to paraphrase:\n{chunk}\n\nParaphrased version:"
+            ),
             temperature=0.4 + (intensity - 1) * 0.15,
-            max_tokens=4096,
+            # A chunk is capped at 3,500 characters, so 2,048 tokens leaves
+            # ample room while avoiding an unnecessarily large generation cap.
+            max_tokens=2048,
         )
         parts.append(part)
 
     return "\n\n".join(parts)
 
 
-def _paraphrase_llm(text: str, intensity: int) -> str:
+def _paraphrase_llm(text: str, intensity: int, writing_mode: str = "standard") -> str:
     from services.llm_client import llm_chat
 
-    return _paraphrase_with_fn(text, intensity, llm_chat)
+    return _paraphrase_with_fn(text, intensity, llm_chat, writing_mode)
 
 
-def _paraphrase_llm_premium(text: str, intensity: int, model: str) -> tuple[str, str]:
+def _paraphrase_llm_premium(
+    text: str,
+    intensity: int,
+    model: str,
+    writing_mode: str = "standard",
+) -> tuple[str, str]:
     from services.llm_client import llm_chat_premium
 
     model_used = "standard"
@@ -132,10 +163,72 @@ def _paraphrase_llm_premium(text: str, intensity: int, model: str) -> tuple[str,
         model_used = mu
         return content
 
-    result = _paraphrase_with_fn(text, intensity, _chat_fn)
+    result = _paraphrase_with_fn(text, intensity, _chat_fn, writing_mode)
     return result, model_used
 
 
+def refine_selection(
+    text: str,
+    selected_text: str,
+    kind: str,
+    writing_mode: str = "standard",
+    intensity: int = 3,
+    count: int = 5,
+) -> list[str]:
+    """Generate contextual alternatives for one sentence or one word."""
+    from services.llm_client import llm_chat
+
+    mode_instruction = MODE_PROMPTS.get(writing_mode, MODE_PROMPTS["standard"])
+    if kind == "word":
+        system_prompt = (
+            "You are a context-aware thesaurus. Suggest replacement words or short phrases "
+            "that fit the exact grammar, tense, number, meaning, and tone of the selected word. "
+            "Do not repeat the selected word. Return only a numbered list, one option per line."
+        )
+        user_prompt = (
+            f"Full text:\n{text}\n\nSelected word: {selected_text}\n"
+            f"Style: {mode_instruction}\nProvide {count} precise replacements."
+        )
+    else:
+        system_prompt = (
+            "You rewrite a selected sentence without changing its meaning. Preserve every fact, "
+            "name, number, qualification, citation, and negation. Each suggestion must stand in "
+            "the same surrounding text. Return only a numbered list, one complete sentence per line."
+        )
+        intensity_instruction = INTENSITY_PROMPTS.get(intensity, INTENSITY_PROMPTS[3])
+        user_prompt = (
+            f"Full text for context:\n{text}\n\nSelected sentence:\n{selected_text}\n\n"
+            f"Style: {mode_instruction}\nChange level: {intensity_instruction}\n"
+            f"Provide {count} distinct, precise alternatives."
+        )
+
+    raw = llm_chat(
+        system_prompt=system_prompt,
+        user_prompt=user_prompt,
+        temperature=0.35 if kind == "word" else 0.65,
+        # Alternatives are short. Smaller caps reduce provider latency and
+        # prevent verbose models from continuing past the requested list.
+        max_tokens=180 if kind == "word" else 600,
+    )
+    return _parse_suggestions(raw, selected_text, count)
+
+
+def _parse_suggestions(raw: str, selected_text: str, count: int) -> list[str]:
+    """Normalize numbered/bulleted LLM output into a stable deduplicated list."""
+    suggestions: list[str] = []
+    selected_key = selected_text.strip().casefold().rstrip(".!?")
+    for line in raw.splitlines():
+        value = re.sub(r"^\s*(?:[-*•]|\d+[.)])\s*", "", line).strip()
+        value = value.strip('"“”')
+        if not value or value.casefold().rstrip(".!?") == selected_key:
+            continue
+        if value.casefold() not in {item.casefold() for item in suggestions}:
+            suggestions.append(value)
+        if len(suggestions) == count:
+            break
+    return suggestions
+
+
 # ── T5 fallback ──────────────────────────────────────────────────────────────
 
 INTENSITY_PARAMS: dict[int, dict] = {

tests/test_api.py

@@ -31,16 +31,20 @@ class TestHealth:
 
 class TestParaphrase:
     def test_paraphrase_success(self):
-        with patch("routers.paraphrase._paraphrase", return_value="A quick fox leapt over a lazy dog."):
+        with patch(
+            "routers.paraphrase._paraphrase",
+            return_value=("A quick fox leapt over a lazy dog.", "standard"),
+        ):
             response = client.post("/api/paraphrase", json={"text": "The quick brown fox jumps over the lazy dog.", "intensity": 3})  # noqa: E501
         assert response.status_code == 200
         data = response.json()
         assert data["original"] == "The quick brown fox jumps over the lazy dog."
         assert data["paraphrased"] == "A quick fox leapt over a lazy dog."
         assert data["intensity"] == 3
+        assert data["writing_mode"] == "standard"
 
     def test_paraphrase_intensity_bounds(self):
-        with patch("routers.paraphrase._paraphrase", return_value="result"):
+        with patch("routers.paraphrase._paraphrase", return_value=("result", "standard")):
             r1 = client.post("/api/paraphrase", json={"text": "Hello world.", "intensity": 1})
             r5 = client.post("/api/paraphrase", json={"text": "Hello world.", "intensity": 5})
         assert r1.status_code == 200
@@ -59,6 +63,25 @@ class TestParaphrase:
             response = client.post("/api/paraphrase", json={"text": "Hello.", "intensity": 3})
         assert response.status_code == 500
 
+    def test_contextual_refine_options(self):
+        with patch(
+            "routers.paraphrase._refine_selection",
+            return_value=["Clear writing makes ideas easier to share.", "Good prose communicates ideas clearly."],
+        ):
+            response = client.post(
+                "/api/paraphrase/refine",
+                json={
+                    "text": "Good writing helps people communicate ideas clearly.",
+                    "selected_text": "Good writing helps people communicate ideas clearly.",
+                    "kind": "sentence",
+                    "writing_mode": "fluency",
+                    "intensity": 3,
+                    "count": 2,
+                },
+            )
+        assert response.status_code == 200
+        assert len(response.json()["suggestions"]) == 2
+
 
 # ── Grammar ───────────────────────────────────────────────────────────────────