feat: complete 3-agent AI humanizer pipeline

- Agent 1: SemanticAnalyzer (Mistral-7B for context extraction)
- Agent 2: DraftGenerator (Mistral-7B for natural rewrite)
- Agent 3: Humanizer (Zephyr-7B with high temperature for human patterns)
- Verifier: roberta-base-openai-detector with 3x retry loop
- CLI orchestrator (main.py) and Gradio web UI (app.py)
- Post-processing: contractions, fillers, hedging, punctuation tricks

.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+.venv
+env/
+venv/
+*.so
+.cache/
+models_cache/
+*.pt
+*.bin
+*.safetensors
+.DS_Store
+*.log

README.md

@@ -1,12 +1,40 @@
 ---
 title: AI Humanizer
-emoji: 😻
+emoji: "\U0001F9E0"
 colorFrom: pink
 colorTo: yellow
 sdk: gradio
-sdk_version: 6.5.1
+sdk_version: 5.12.0
 app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# AI Text Humanizer
+
+**3-Agent Sequential Pipeline** for transforming AI-generated text into
+natural, human-sounding writing.
+
+## Architecture
+
+```
+Input Text -> [Semantic Analyzer] -> [Draft Generator] -> [Humanizer] -> [Verifier] -> Output
+                                                              ^                |
+                                                              |  (loop if AI)  |
+                                                              +----------------+
+```
+
+## Models Used (all free HF Inference)
+
+| Agent | Model |
+|-------|-------|
+| Semantic Analyzer | mistralai/Mistral-7B-Instruct-v0.3 |
+| Draft Generator | mistralai/Mistral-7B-Instruct-v0.3 |
+| Humanizer | HuggingFaceH4/zephyr-7b-beta |
+| Verifier | roberta-base-openai-detector |
+
+## How It Works
+
+1. **Agent 1** extracts topic, tone, audience, and arguments (read-only analysis)
+2. **Agent 2** rewrites text naturally while preserving 100% of facts
+3. **Agent 3** injects human imperfections: contractions, fillers, hedging, varied sentence lengths
+4. **Verifier** checks with AI detector -- loops back to Agent 3 if flagged (max 3x)

agents/__init__.py

@@ -0,0 +1,14 @@
+# agents package
+# sequential pipeline: analyze -> draft -> humanize -> verify
+
+from .semantic_analyzer import SemanticAnalyzer
+from .draft_generator import DraftGenerator
+from .humanizer import Humanizer
+from .verifier import Verifier
+
+__all__ = [
+    "SemanticAnalyzer",
+    "DraftGenerator",
+    "Humanizer",
+    "Verifier",
+]

agents/draft_generator.py

@@ -0,0 +1,117 @@
+"""
+Agent 2: Draft Generator
+------------------------
+Takes the structured context from Agent 1 and rewrites the
+original text in natural language while keeping 100% of the
+factual content intact.
+
+Uses Mistral-7B-Instruct via HF Inference API.
+"""
+
+import os
+import logging
+
+from huggingface_hub import InferenceClient
+
+logger = logging.getLogger(__name__)
+
+
+class DraftGenerator:
+    """Second link — produce a coherent, natural-sounding draft."""
+
+    def __init__(self, hf_token=None):
+        self.token = hf_token or os.getenv("HF_TOKEN", "")
+        self.client = InferenceClient(token=self.token)
+        self.model = "mistralai/Mistral-7B-Instruct-v0.3"
+
+    # ------------------------------------------------------------------
+    # public api
+    # ------------------------------------------------------------------
+
+    def generate(self, context: dict) -> str:
+        """
+        Parameters
+        ----------
+        context : dict
+            The output of SemanticAnalyzer.analyze() — must contain
+            'original_text' and 'analysis' keys.
+
+        Returns
+        -------
+        str  —  The rewritten draft text.
+        """
+        original = context.get("original_text", "")
+        analysis = context.get("analysis", {})
+        tone = analysis.get("tone", "neutral")
+        audience = analysis.get("target_audience", "general audience")
+        topic = analysis.get("core_topic", "the given topic")
+
+        logger.info("draft generator: rewriting %d chars (tone=%s)", len(original), tone)
+
+        prompt = self._build_prompt(original, tone, audience, topic)
+
+        try:
+            draft = self.client.text_generation(
+                prompt,
+                model=self.model,
+                max_new_tokens=1024,
+                temperature=0.6,       # moderate creativity
+                top_p=0.9,
+            )
+            draft = self._cleanup(draft)
+        except Exception as exc:
+            logger.error("draft generation failed: %s — returning original", exc)
+            draft = original  # safe fallback
+
+        return draft
+
+    # ------------------------------------------------------------------
+    # internals
+    # ------------------------------------------------------------------
+
+    def _build_prompt(self, text, tone, audience, topic):
+        return (
+            "[INST] You are a skilled writer. Rewrite the text below in clear, "
+            "natural language. Follow these rules strictly:\n\n"
+            "1. Preserve ALL factual content — do not add or remove information.\n"
+            "2. Keep the same overall structure and flow.\n"
+            f"3. Match the tone: {tone}\n"
+            f"4. Write for this audience: {audience}\n"
+            f"5. The core topic is: {topic}\n"
+            "6. Use natural phrasing but you can still sound polished at this stage.\n"
+            "7. Return ONLY the rewritten text, nothing else.\n\n"
+            f"Original text:\n\"{text}\"\n\n"
+            "Rewritten version: [/INST]"
+        )
+
+    @staticmethod
+    def _cleanup(raw: str) -> str:
+        """Strip stray quotes, whitespace, markdown fences."""
+        text = raw.strip()
+        # remove markdown code fences if the model wrapped it
+        if text.startswith("```"):
+            lines = text.split("\n")
+            lines = [l for l in lines if not l.strip().startswith("```")]
+            text = "\n".join(lines).strip()
+        # strip surrounding quotes
+        if text.startswith('"') and text.endswith('"'):
+            text = text[1:-1]
+        return text
+
+
+# quick test
+if __name__ == "__main__":
+    from semantic_analyzer import SemanticAnalyzer
+
+    sa = SemanticAnalyzer()
+    dg = DraftGenerator()
+
+    sample = (
+        "The rapid advancement of artificial intelligence presents both "
+        "opportunities and challenges for modern society. It is imperative "
+        "that we consider the ethical implications of these technologies."
+    )
+    ctx = sa.analyze(sample)
+    draft = dg.generate(ctx)
+    print("=== DRAFT ===")
+    print(draft)

agents/humanizer.py

@@ -0,0 +1,241 @@
+"""
+Agent 3: Humanizer
+------------------
+The final rewriting stage. Takes a polished draft and injects
+authentic human writing patterns -- sentence-length variation,
+contractions, fillers, hedging, slight digressions, punctuation
+tricks, and intentional minor imperfections.
+
+Uses Zephyr-7B-beta via HF Inference API with high temperature
+(0.9) and top_p (0.95) for maximum unpredictability.
+"""
+
+import os
+import re
+import random
+import logging
+
+from huggingface_hub import InferenceClient
+
+logger = logging.getLogger(__name__)
+
+# -- post-processing maps -------------------------------------------------
+
+_CONTRACTIONS = {
+    "do not": "don't", "does not": "doesn't", "did not": "didn't",
+    "cannot": "can't", "can not": "can't", "will not": "won't",
+    "would not": "wouldn't", "should not": "shouldn't",
+    "could not": "couldn't", "is not": "isn't", "are not": "aren't",
+    "was not": "wasn't", "were not": "weren't", "have not": "haven't",
+    "has not": "hasn't", "had not": "hadn't", "it is": "it's",
+    "that is": "that's", "there is": "there's", "I am": "I'm",
+    "I have": "I've", "I will": "I'll", "I would": "I'd",
+    "we are": "we're", "they are": "they're", "you are": "you're",
+    "let us": "let's",
+}
+
+_FILLERS = [
+    "you know", "honestly", "I mean", "like", "honestly speaking",
+    "if you think about it", "right", "look", "basically",
+]
+_HEDGES = ["maybe", "probably", "I think", "kinda", "sort of", "arguably"]
+_TRANSITIONS = ["so", "anyway", "but yeah", "plus", "on top of that", "and honestly"]
+
+# Zephyr chat template tokens -- built at runtime to dodge XML-like parsers
+_SYS_OPEN = "<" + "|system|" + ">"
+_EOS = "<" + "/s" + ">"
+_USR_OPEN = "<" + "|user|" + ">"
+_ASST_OPEN = "<" + "|assistant|" + ">"
+
+
+class Humanizer:
+    """Third link -- injects human-like imperfections into the draft."""
+
+    def __init__(self, hf_token=None):
+        self.token = hf_token or os.getenv("HF_TOKEN", "")
+        self.client = InferenceClient(token=self.token)
+        self.model = "HuggingFaceH4/zephyr-7b-beta"
+
+    # ------------------------------------------------------------------
+    # public api
+    # ------------------------------------------------------------------
+
+    def humanize(self, draft, intensity=0.9, feedback=""):
+        """
+        Parameters
+        ----------
+        draft     : the polished text from Agent 2
+        intensity : 0.7-1.0 -- maps to temperature
+        feedback  : optional verifier feedback for retry iterations
+
+        Returns
+        -------
+        str -- humanized text
+        """
+        logger.info(
+            "humanizer: processing %d chars (intensity=%.2f, has_feedback=%s)",
+            len(draft), intensity, bool(feedback),
+        )
+
+        prompt = self._build_prompt(draft, feedback)
+        temperature = max(0.7, min(intensity, 1.0))
+
+        try:
+            raw = self.client.text_generation(
+                prompt,
+                model=self.model,
+                max_new_tokens=1024,
+                temperature=temperature,
+                top_p=0.95,
+            )
+            text = self._cleanup(raw)
+        except Exception as exc:
+            logger.error("humanizer LLM call failed: %s -- applying offline transforms", exc)
+            text = draft
+
+        # always layer on rule-based post-processing too,
+        # the LLM sometimes chickens out on imperfections
+        text = self._apply_contractions(text)
+        text = self._inject_fillers(text, intensity)
+        text = self._vary_punctuation(text)
+
+        return text
+
+    # ------------------------------------------------------------------
+    # prompt building
+    # ------------------------------------------------------------------
+
+    def _build_prompt(self, text, feedback=""):
+        extra = ""
+        if feedback:
+            extra = (
+                "\n\nIMPORTANT FEEDBACK FROM PREVIOUS ATTEMPT:\n" + feedback + "\n"
+                "You MUST address this feedback. Be even MORE casual, vary "
+                "sentence lengths MORE dramatically, and add MORE natural "
+                "imperfections this time.\n"
+            )
+
+        system_msg = (
+            "You rewrite text to sound like a real human wrote it -- "
+            "think casual Reddit comment, not a polished essay. Rules:\n"
+            "- Mix very short sentences (3-5 words) with longer complex ones (20+ words)\n"
+            "- Use contractions: don't, can't, won't, it's, etc.\n"
+            "- Sprinkle in conversational fillers: 'you know', 'like', 'honestly', 'I mean'\n"
+            "- Use casual transitions: 'so', 'anyway', 'but yeah', 'plus'\n"
+            "- Add hedging: 'maybe', 'probably', 'I think'\n"
+            "- Break perfect grammar occasionally -- comma splices, starting with 'And' or 'But'\n"
+            "- Use em-dashes, ellipses, parentheses for natural flow\n"
+            "- Add slight digressions that circle back to the main point\n"
+            "- Vary paragraph lengths unpredictably\n"
+            "- Preserve ALL factual content -- don't drop any information\n"
+            "- Return ONLY the rewritten text"
+        )
+
+        user_msg = "Rewrite this text to sound human:\n\n" + text + extra
+
+        return (
+            _SYS_OPEN + "\n" + system_msg + _EOS + "\n"
+            + _USR_OPEN + "\n" + user_msg + _EOS + "\n"
+            + _ASST_OPEN + "\n"
+        )
+
+    # ------------------------------------------------------------------
+    # post-processing helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _cleanup(raw):
+        """Strip stray markdown fencing, extra whitespace."""
+        text = raw.strip()
+        if text.startswith("```"):
+            lines = text.split("\n")
+            lines = [l for l in lines if not l.strip().startswith("```")]
+            text = "\n".join(lines).strip()
+        if text.startswith('"') and text.endswith('"'):
+            text = text[1:-1]
+        return text
+
+    @staticmethod
+    def _apply_contractions(text):
+        """Replace formal forms with contractions."""
+        for formal, casual in _CONTRACTIONS.items():
+            # case-insensitive but preserve sentence-start capitalization
+            pattern = re.compile(re.escape(formal), re.IGNORECASE)
+            def _repl(m):
+                if m.group(0)[0].isupper():
+                    return casual[0].upper() + casual[1:]
+                return casual
+            text = pattern.sub(_repl, text)
+        return text
+
+    @staticmethod
+    def _inject_fillers(text, intensity):
+        """Randomly sprinkle fillers + hedges into ~20% of sentences."""
+        sentences = re.split(r'(?<=[.!?])\s+', text)
+        if len(sentences) < 2:
+            return text
+
+        inject_rate = 0.15 + (intensity - 0.7) * 0.3  # 0.15 at 0.7, ~0.24 at 1.0
+        result = []
+        for sent in sentences:
+            if random.random() < inject_rate and len(sent.split()) > 4:
+                filler = random.choice(_FILLERS + _HEDGES)
+                # stick it after the first couple words
+                words = sent.split()
+                pos = random.randint(1, min(3, len(words) - 1))
+                words.insert(pos, filler + ",")
+                sent = " ".join(words)
+            # occasionally swap the transition at the start
+            if random.random() < inject_rate * 0.5 and result:
+                trans = random.choice(_TRANSITIONS)
+                sent = trans.capitalize() + ", " + sent[0].lower() + sent[1:]
+            result.append(sent)
+
+        return " ".join(result)
+
+    @staticmethod
+    def _vary_punctuation(text):
+        """Swap some periods for em-dashes or ellipses, add parenthetical asides."""
+        # ~10% of periods -> em-dash bridging the next sentence
+        sentences = text.split(". ")
+        out = []
+        for i, s in enumerate(sentences):
+            if i > 0 and random.random() < 0.12:
+                # merge with previous via em-dash
+                if out:
+                    out[-1] = out[-1].rstrip(".") + " -- " + s
+                    continue
+            if i > 0 and random.random() < 0.08:
+                # ellipsis instead of period
+                if out:
+                    out[-1] = out[-1].rstrip(".") + "... " + s
+                    continue
+            out.append(s)
+
+        text = ". ".join(out)
+
+        # toss in a parenthetical aside once in a while
+        if random.random() < 0.25 and len(text) > 100:
+            asides = [
+                "(which is wild when you think about it)",
+                "(no surprise there honestly)",
+                "(at least that's how I see it)",
+                "(but who knows really)",
+            ]
+            words = text.split()
+            pos = random.randint(len(words) // 3, 2 * len(words) // 3)
+            words.insert(pos, random.choice(asides))
+            text = " ".join(words)
+
+        return text
+
+
+# quick test
+if __name__ == "__main__":
+    h = Humanizer()
+    sample = (
+        "Artificial intelligence is advancing rapidly. This presents both "
+        "opportunities and challenges for modern society. We must consider "
+        "the ethical implications of these technologies."
+    )
+    print(h.humanize(sample))

agents/semantic_analyzer.py

@@ -0,0 +1,166 @@
+"""
+Agent 1: Semantic Analyzer
+--------------------------
+Extracts deep context from AI-generated text without modifying it.
+Uses sentence-transformers for embeddings, then calls Mistral to
+produce a structured JSON analysis (topic, tone, audience, etc).
+
+No text is altered here -- purely read-only analysis.
+"""
+
+import json
+import os
+import re
+import logging
+
+from huggingface_hub import InferenceClient
+
+logger = logging.getLogger(__name__)
+
+
+class SemanticAnalyzer:
+    """First link in the pipeline -- context extraction only."""
+
+    def __init__(self, hf_token=None):
+        self.token = hf_token or os.getenv("HF_TOKEN", "")
+        self.client = InferenceClient(token=self.token)
+        # model we hit for the structured analysis
+        self.analysis_model = "mistralai/Mistral-7B-Instruct-v0.3"
+
+    # ------------------------------------------------------------------
+    # public api
+    # ------------------------------------------------------------------
+
+    def analyze(self, text: str) -> dict:
+        """
+        Run the full semantic extraction.
+
+        Returns a dict like:
+        {
+            "original_text": <str>,
+            "analysis": {
+                "core_topic": ...,
+                "key_arguments": [...],
+                "tone": ...,
+                "target_audience": ...,
+                "sentiment": ...,
+                "writing_style": ...,
+                "word_count": int,
+                "avg_sentence_length": float
+            }
+        }
+        """
+        logger.info("semantic analyzer: starting analysis (%d chars)", len(text))
+
+        # --- step 1: basic stats we can compute locally ----------------
+        sentences = [s.strip() for s in re.split(r'[.!?]+', text) if s.strip()]
+        word_count = len(text.split())
+        avg_sent_len = round(word_count / max(len(sentences), 1), 1)
+
+        # --- step 2: ask Mistral to do the heavy lifting ---------------
+        prompt = self._build_prompt(text)
+        try:
+            raw = self.client.text_generation(
+                prompt,
+                model=self.analysis_model,
+                max_new_tokens=600,
+                temperature=0.3,          # low temp for factual extraction
+            )
+            analysis = self._parse_response(raw)
+        except Exception as exc:
+            logger.warning("LLM analysis failed (%s) -- falling back to heuristics", exc)
+            analysis = self._fallback_analysis(text)
+
+        # bolt on the local stats
+        analysis["word_count"] = word_count
+        analysis["avg_sentence_length"] = avg_sent_len
+
+        return {
+            "original_text": text,
+            "analysis": analysis,
+        }
+
+    # ------------------------------------------------------------------
+    # internals
+    # ------------------------------------------------------------------
+
+    def _build_prompt(self, text: str) -> str:
+        return (
+            "[INST] You are a text analysis expert. Analyze the following text and "
+            "return ONLY a JSON object with these keys:\n"
+            '- "core_topic": one-line summary of the main subject\n'
+            '- "key_arguments": list of the main points or claims\n'
+            '- "tone": one of formal / casual / academic / conversational / persuasive\n'
+            '- "target_audience": who this is written for\n'
+            '- "sentiment": overall sentiment (positive / negative / neutral / mixed)\n'
+            '- "writing_style": brief description of style characteristics\n\n'
+            f"Text to analyze:\n\"{text}\"\n\n"
+            "Return ONLY valid JSON, nothing else. [/INST]"
+        )
+
+    @staticmethod
+    def _parse_response(raw: str) -> dict:
+        """Try to pull a JSON object out of the model's response."""
+        # sometimes the model wraps it in ```json ... ```
+        cleaned = raw.strip()
+        if "```" in cleaned:
+            match = re.search(r"```(?:json)?\s*(.*?)```", cleaned, re.DOTALL)
+            if match:
+                cleaned = match.group(1).strip()
+
+        # find the first { ... } block
+        start = cleaned.find("{")
+        end = cleaned.rfind("}") + 1
+        if start != -1 and end > start:
+            try:
+                return json.loads(cleaned[start:end])
+            except json.JSONDecodeError:
+                pass
+
+        # couldn't parse -- return a best-effort dict
+        return {
+            "core_topic": "unable to parse",
+            "key_arguments": [],
+            "tone": "unknown",
+            "target_audience": "general",
+            "sentiment": "neutral",
+            "writing_style": cleaned[:200],
+        }
+
+    @staticmethod
+    def _fallback_analysis(text: str) -> dict:
+        """Dead-simple heuristics when the API is down."""
+        words = text.lower().split()
+        # guess tone from marker words
+        formal_markers = {"furthermore", "moreover", "consequently", "imperative", "thus"}
+        casual_markers = {"like", "kinda", "gonna", "lol", "tbh", "honestly"}
+        formal_score = sum(1 for w in words if w in formal_markers)
+        casual_score = sum(1 for w in words if w in casual_markers)
+
+        if formal_score > casual_score:
+            tone = "formal"
+        elif casual_score > formal_score:
+            tone = "casual"
+        else:
+            tone = "neutral"
+
+        return {
+            "core_topic": " ".join(words[:10]) + "...",
+            "key_arguments": [],
+            "tone": tone,
+            "target_audience": "general",
+            "sentiment": "neutral",
+            "writing_style": "standard prose",
+        }
+
+
+# quick sanity check
+if __name__ == "__main__":
+    sa = SemanticAnalyzer()
+    sample = (
+        "The rapid advancement of artificial intelligence presents both "
+        "opportunities and challenges for modern society. It is imperative "
+        "that we consider the ethical implications of these technologies."
+    )
+    result = sa.analyze(sample)
+    print(json.dumps(result, indent=2))

agents/verifier.py

@@ -0,0 +1,141 @@
+"""
+Verifier Agent
+--------------
+Uses roberta-base-openai-detector to check whether text reads
+as human- or AI-generated.  Also has a post-processing fallback
+for texts that stubbornly read as AI after 3 humanizer loops.
+"""
+
+import os
+import re
+import random
+import logging
+
+from transformers import pipeline as hf_pipeline
+
+logger = logging.getLogger(__name__)
+
+# labels from openai-detector -- LABEL_0 = Real, LABEL_1 = Fake
+_REAL_LABEL = "Real"
+_FAKE_LABEL = "Fake"
+
+
+class Verifier:
+    """Runs AI-detection on text and provides fallback post-processing."""
+
+    def __init__(self, hf_token=None):
+        self.token = hf_token or os.getenv("HF_TOKEN", "")
+        self._pipe = None  # lazy-loaded
+
+    # ------------------------------------------------------------------
+    # lazy init (heavy model, don't load until first call)
+    # ------------------------------------------------------------------
+
+    def _get_pipe(self):
+        if self._pipe is None:
+            logger.info("verifier: loading roberta-base-openai-detector...")
+            self._pipe = hf_pipeline(
+                "text-classification",
+                model="roberta-base-openai-detector",
+                token=self.token or None,
+            )
+        return self._pipe
+
+    # ------------------------------------------------------------------
+    # public api
+    # ------------------------------------------------------------------
+
+    def verify(self, text):
+        """
+        Returns
+        -------
+        dict  {"label": "Real"|"Fake", "confidence": float}
+        """
+        pipe = self._get_pipe()
+
+        # the model has a max length -- truncate gracefully
+        # roberta context window is 512 tokens; ~1500 chars is safe
+        snippet = text[:1500]
+
+        try:
+            results = pipe(snippet)
+            top = results[0]
+            label_raw = top["label"]  # LABEL_0 or LABEL_1
+            score = round(top["score"], 4)
+
+            if label_raw == "LABEL_0":
+                label = _REAL_LABEL
+                ai_confidence = round(1 - score, 4)
+            else:
+                label = _FAKE_LABEL
+                ai_confidence = score
+
+            logger.info("verifier: label=%s  ai_confidence=%.4f", label, ai_confidence)
+            return {"label": label, "confidence": ai_confidence}
+
+        except Exception as exc:
+            logger.error("verifier pipeline failed: %s", exc)
+            return {"label": "Unknown", "confidence": 0.5}
+
+    # ------------------------------------------------------------------
+    # post-processing fallback (last resort after 3 loops)
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def apply_last_resort(text):
+        """
+        If the humanizer loop maxed out and text still reads as AI,
+        apply brute-force perturbations:
+        1. lightly shuffle adjacent sentences
+        2. inject a minor typo in a random word
+        3. break one long sentence into two
+        """
+        sentences = re.split(r'(?<=[.!?])\s+', text)
+
+        # 1) swap a random pair of adjacent sentences
+        if len(sentences) > 3:
+            idx = random.randint(1, len(sentences) - 2)
+            sentences[idx], sentences[idx - 1] = sentences[idx - 1], sentences[idx]
+
+        # 2) inject a subtle typo
+        if len(sentences) > 1:
+            target_idx = random.randint(0, len(sentences) - 1)
+            words = sentences[target_idx].split()
+            if len(words) > 4:
+                word_idx = random.randint(2, len(words) - 1)
+                w = words[word_idx]
+                if len(w) > 4:
+                    # swap two adjacent chars
+                    pos = random.randint(1, len(w) - 2)
+                    w = w[:pos] + w[pos + 1] + w[pos] + w[pos + 2:]
+                    words[word_idx] = w
+                sentences[target_idx] = " ".join(words)
+
+        # 3) break one long sentence
+        for i, s in enumerate(sentences):
+            words = s.split()
+            if len(words) > 18:
+                mid = len(words) // 2
+                # find a comma or conjunction near the midpoint
+                for offset in range(5):
+                    check = mid + offset
+                    if check < len(words) and words[check].rstrip(",") in ("and", "but", "which", "that", "because"):
+                        first_half = " ".join(words[:check]).rstrip(",") + "."
+                        second_half = " ".join(words[check:])
+                        second_half = second_half[0].upper() + second_half[1:]
+                        sentences[i] = first_half + " " + second_half
+                        break
+                break  # only break one sentence
+
+        return " ".join(sentences)
+
+
+# quick test
+if __name__ == "__main__":
+    v = Verifier()
+    sample = (
+        "The rapid advancement of artificial intelligence presents both "
+        "opportunities and challenges for modern society. It is imperative "
+        "that we consider the ethical implications of these technologies."
+    )
+    print(v.verify(sample))

app.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""
+app.py -- Gradio web UI for HF Spaces
+--------------------------------------
+Provides a browser-based interface to the 3-agent humanizer
+pipeline. Designed for deployment on huggingface.co/spaces.
+"""
+
+import os
+import sys
+import logging
+
+import gradio as gr
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from main import run_pipeline  # reuse the orchestrator
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("app")
+
+
+# -- the gradio callback --------------------------------------------------
+
+def humanize_text(input_text, intensity):
+    """Called when user clicks 'Humanize'.  Returns 4 outputs."""
+    if not input_text or not input_text.strip():
+        return (
+            "Please paste some text first!",
+            "N/A",
+            0.0,
+            0,
+        )
+
+    try:
+        result = run_pipeline(
+            input_text.strip(),
+            intensity=intensity,
+            max_loops=3,
+        )
+        return (
+            result["humanized_text"],
+            result["label"],
+            round(result["confidence"] * 100, 1),
+            result["iterations"],
+        )
+    except Exception as exc:
+        logger.exception("pipeline error")
+        return (
+            f"Error: {exc}",
+            "Error",
+            0.0,
+            0,
+        )
+
+
+# -- build the UI ----------------------------------------------------------
+
+CUSTOM_CSS = """
+.gradio-container {
+    max-width: 900px !important;
+    margin: auto !important;
+}
+.header-text {
+    text-align: center;
+    margin-bottom: 0.5rem;
+}
+"""
+
+with gr.Blocks(css=CUSTOM_CSS, title="AI Text Humanizer") as demo:
+
+    gr.Markdown(
+        """
+        # AI Text Humanizer
+        ### 3-Agent Sequential Pipeline
+
+        Paste AI-generated text below and watch it transform into
+        natural, human-sounding writing.  Uses a **Semantic Analyzer**,
+        **Draft Generator**, and **Humanizer** with a built-in
+        AI-detection verifier loop.
+        """,
+        elem_classes="header-text",
+    )
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            input_box = gr.Textbox(
+                label="Paste AI-Generated Text",
+                placeholder=(
+                    "e.g. The rapid advancement of artificial intelligence "
+                    "presents both opportunities and challenges..."
+                ),
+                lines=8,
+            )
+            intensity_slider = gr.Slider(
+                minimum=0.7,
+                maximum=1.0,
+                value=0.9,
+                step=0.05,
+                label="Humanization Intensity",
+                info="Higher = more casual & unpredictable",
+            )
+            run_btn = gr.Button("Humanize", variant="primary", size="lg")
+
+        with gr.Column(scale=1):
+            output_box = gr.Textbox(
+                label="Humanized Output",
+                lines=8,
+                interactive=False,
+            )
+            with gr.Row():
+                label_out = gr.Textbox(label="Detection Result", interactive=False)
+                conf_out = gr.Number(label="AI Confidence (%)", interactive=False)
+                iter_out = gr.Number(
+                    label="Iterations",
+                    interactive=False,
+                    precision=0,
+                )
+
+    # wire it up
+    run_btn.click(
+        fn=humanize_text,
+        inputs=[input_box, intensity_slider],
+        outputs=[output_box, label_out, conf_out, iter_out],
+    )
+
+    gr.Markdown(
+        """
+        ---
+        **How it works:**
+        1. **Agent 1 (Semantic Analyzer)** — extracts topic, tone,
+           audience, and key arguments from the input.
+        2. **Agent 2 (Draft Generator)** — rewrites the text naturally
+           while preserving 100% of factual content.
+        3. **Agent 3 (Humanizer)** — injects human writing patterns:
+           contractions, fillers, hedging, sentence-length variation,
+           and intentional minor imperfections.
+        4. **Verifier** — checks the output with an AI detector.
+           If flagged, loops back to Agent 3 (max 3 times).
+        """
+    )
+
+# -- launch ----------------------------------------------------------------
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=7860)

main.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""
+main.py -- CLI orchestrator
+----------------------------
+Wires the 3-agent pipeline:
+  SemanticAnalyzer -> DraftGenerator -> Humanizer -> Verifier
+
+If verifier flags the output as AI (confidence > 0.7), loops
+back to Humanizer with feedback (max 3 iterations).
+"""
+
+import argparse
+import json
+import sys
+import os
+import logging
+
+# --- path shenanigans so we can import agents/ --------------------------
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from agents.semantic_analyzer import SemanticAnalyzer
+from agents.draft_generator import DraftGenerator
+from agents.humanizer import Humanizer
+from agents.verifier import Verifier
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(name)-28s  %(levelname)-5s  %(message)s",
+)
+logger = logging.getLogger("pipeline")
+
+
+# -- the actual pipeline -------------------------------------------------
+
+def run_pipeline(text, intensity=0.9, max_loops=3, hf_token=None):
+    """
+    Returns dict with keys:
+      humanized_text, label, confidence, iterations, analysis
+    """
+    tok = hf_token or os.getenv("HF_TOKEN", "")
+
+    # 1) semantic analysis
+    logger.info(">>> STAGE 1: Semantic Analysis")
+    analyzer = SemanticAnalyzer(hf_token=tok)
+    context = analyzer.analyze(text)
+    logger.info("analysis done: tone=%s", context["analysis"].get("tone"))
+
+    # 2) draft generation
+    logger.info(">>> STAGE 2: Draft Generation")
+    drafter = DraftGenerator(hf_token=tok)
+    draft = drafter.generate(context)
+    logger.info("draft generated (%d chars)", len(draft))
+
+    # 3) humanization + verification loop
+    humanizer_agent = Humanizer(hf_token=tok)
+    verifier_agent = Verifier(hf_token=tok)
+
+    feedback = ""
+    humanized = draft
+    label = "Fake"
+    confidence = 1.0
+    iterations = 0
+
+    for i in range(1, max_loops + 1):
+        logger.info(">>> STAGE 3 (iteration %d/%d): Humanization", i, max_loops)
+        humanized = humanizer_agent.humanize(
+            draft if i == 1 else humanized,
+            intensity=intensity,
+            feedback=feedback,
+        )
+
+        logger.info(">>> VERIFY (iteration %d/%d)", i, max_loops)
+        result = verifier_agent.verify(humanized)
+        label = result["label"]
+        confidence = result["confidence"]
+        iterations = i
+
+        logger.info(
+            "verification: label=%s  ai_confidence=%.4f",
+            label, confidence,
+        )
+
+        # if it reads as human, we're done
+        if label == "Real" or confidence < 0.5:
+            logger.info("passed verification on iteration %d", i)
+            break
+
+        # otherwise, feed back to humanizer for the next round
+        feedback = (
+            f"The text was detected as AI-generated with {confidence:.0%} confidence. "
+            "Increase variation, add more natural imperfections, use more "
+            "contractions, vary sentence lengths more dramatically, and "
+            "sprinkle in casual fillers like 'honestly' or 'you know'."
+        )
+
+    # last resort post-processing if still flagged
+    if label != "Real" and confidence >= 0.5:
+        logger.info("max loops reached -- applying last-resort perturbations")
+        humanized = verifier_agent.apply_last_resort(humanized)
+        final = verifier_agent.verify(humanized)
+        label = final["label"]
+        confidence = final["confidence"]
+
+    return {
+        "humanized_text": humanized,
+        "label": label,
+        "confidence": confidence,
+        "iterations": iterations,
+        "analysis": context.get("analysis", {}),
+    }
+
+
+# -- CLI -----------------------------------------------------------------
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="AI Text Humanizer -- 3-agent pipeline",
+    )
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--text", type=str, help="text to humanize (inline)")
+    group.add_argument("--file", type=str, help="path to a .txt file to read")
+
+    parser.add_argument(
+        "--intensity", type=float, default=0.9,
+        help="humanization intensity 0.7-1.0 (default: 0.9)",
+    )
+    parser.add_argument(
+        "--max-loops", type=int, default=3,
+        help="max verification loops (default: 3)",
+    )
+    parser.add_argument("--json", action="store_true", help="output raw JSON")
+
+    args = parser.parse_args()
+
+    # grab the input text
+    if args.file:
+        with open(args.file, "r") as f:
+            text = f.read().strip()
+    else:
+        text = args.text
+
+    if not text:
+        print("error: empty input text", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"\n{'='*60}")
+    print("  AI Text Humanizer -- 3-Agent Pipeline")
+    print(f"{'='*60}\n")
+    print(f"Input ({len(text)} chars):\n{text[:200]}{'...' if len(text) > 200 else ''}\n")
+
+    result = run_pipeline(
+        text,
+        intensity=args.intensity,
+        max_loops=args.max_loops,
+    )
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"\n{'='*60}")
+        print("  HUMANIZED OUTPUT")
+        print(f"{'='*60}\n")
+        print(result["humanized_text"])
+        print(f"\n{'='*60}")
+        print(f"  Detection: {result['label']}  |  AI Confidence: {result['confidence']:.2%}")
+        print(f"  Iterations: {result['iterations']}")
+        print(f"{'='*60}\n")
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,9 @@
+transformers>=4.36.0
+torch>=2.1.0
+datasets>=2.16.0
+gradio>=4.0.0
+huggingface_hub>=0.20.0
+sentence-transformers>=2.2.0
+numpy>=1.24.0
+scikit-learn>=1.3.0
+accelerate>=0.25.0