ClauseGuard: AI contract analysis with Qwen2.5 via vLLM on AMD

.env.example

@@ -0,0 +1,19 @@
+# ClauseGuard Configuration
+# ─────────────────────────────
+# The Qwen model is served via vLLM with an OpenAI-compatible API.
+# No API key is required for local/self-hosted vLLM deployments.
+# Set API_KEY to a real key only if your vLLM server enforces authentication.
+
+API_KEY=EMPTY
+BASE_URL=http://165.245.141.170:8000/v1
+MODEL_NAME=Qwen/Qwen2.5-1.5B-Instruct
+
+# Optional: override these defaults
+# MAX_TOKENS=4096
+# TIMEOUT_SECONDS=120
+# TEMPERATURE=0.0
+
+# Legacy DeepSeek compatibility (also accepted as fallback)
+# DEEPSEEK_API_KEY=sk-xxx
+# BASE_URL=https://api.deepseek.com
+# MODEL_NAME=deepseek-chat

.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+.pytest_cache/
+.env
+*.pyc
+report.md
+clauseGuard-AI/
+documents/
+frontend/

.streamlit/config.toml

@@ -0,0 +1,7 @@
+[theme]
+base="dark"
+primaryColor="#667eea"
+backgroundColor="#0e1117"
+secondaryBackgroundColor="#1a1a2e"
+textColor="#fafafa"
+font="sans serif"

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ClauseGuard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,15 +1,108 @@
----
-title: ClauseGuard AI
-emoji: 🏢
-colorFrom: green
-colorTo: green
-sdk: gradio
-sdk_version: 6.14.0
-python_version: '3.13'
-app_file: app.py
-pinned: false
-license: mit
-short_description: ClauseGuard helps you understand fix, and negotiate contract
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# ClauseGuard — AI-Powered Contract Clause Risk Analyzer
+
+Upload any contract (PDF, TXT, DOCX). ClauseGuard runs it through a 5-agent AI pipeline and outputs a structured risk report classifying every clause by severity with plain-English explanations.
+
+## Architecture
+
+![ClauseGuard 5-Agent Pipeline](docs/architecture.png)
+
+```
+  ┌──────────┐    ┌───────────┐    ┌─────────────┐    ┌──────────────┐    ┌──────────┐
+  │ Extractor│───▶│Classifier │───▶│ Risk Scorer │───▶│  Translator  │───▶│ Reporter │
+  │ (Agent 1)│    │ (Agent 2) │    │  (Agent 3)  │    │  (Agent 4)   │    │ (Agent 5)│
+  └──────────┘    └───────────┘    └─────────────┘    └──────────────┘    └──────────┘
+       │               │                 │                   │                 │
+       ▼               ▼                 ▼                   ▼                 ▼
+  Split text      Assign types     Score severity      Plain English     Final markdown
+  into clauses    + contract       per clause          + actions         report
+                  type
+```
+
+Agents communicate via OpenAI Agents SDK `handoff()`, passing structured Pydantic v2 output at each stage. If any agent times out (30s limit) or fails, the pipeline continues with partial data — the Reporter always produces a FinalReport.
+
+## Prerequisites
+
+- Python 3.11+
+- [DeepSeek API key](https://platform.deepseek.com/) (OpenAI-compatible endpoint)
+
+## Setup
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd clauseguard
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Configure your API key
+cp .env.example .env
+# Edit .env and add your DEEPSEEK_API_KEY
+```
+
+## Usage
+
+### CLI
+
+```bash
+python main.py --file sample_contracts/sample_nda.txt
+python main.py --file sample_contracts/sample_nda.txt --output my_report.md
+```
+
+### Streamlit UI
+
+```bash
+streamlit run app.py
+```
+
+Open http://localhost:8501 in your browser, upload a contract, and click Analyze.
+
+### Run Tests
+
+```bash
+pytest tests/ -v
+```
+
+## Sample Output
+
+```markdown
+# ClauseGuard Risk Report
+**Contract:** sample_nda.txt
+**Type:** NDA
+**Overall Risk Score:** 5.0/10
+
+## Top 3 Actions Before Signing
+1. Demand a carve-out for inventions created on own time using own equipment
+2. Negotiate to limit the non-compete to specific geographic regions
+3. Negotiate to add an opt-out clause for arbitration
+
+## Risk Summary
+| Severity | Count |
+|----------|-------|
+| 🔴 Critical | 1 |
+| 🟠 High | 2 |
+| 🟡 Medium | 1 |
+| 🟢 Low | 2 |
+| ℹ️ Info | 2 |
+```
+
+## AMD Developer Cloud Deployment
+
+ClauseGuard is designed to run on AMD Developer Cloud infrastructure. The DeepSeek API provides the LLM backend, and the application itself is a lightweight Python service suitable for containerized deployment.
+
+### Docker deployment
+
+```dockerfile
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+COPY . .
+ENV STREAMLIT_SERVER_PORT=8501
+EXPOSE 8501
+CMD ["streamlit", "run", "app.py", "--server.address=0.0.0.0"]
+```
+
+## License
+
+MIT

agents/__init__.py

@@ -0,0 +1,5 @@
+"""ClauseGuard AI agents package."""
+
+from clauseguard.agents.orchestrator import run_pipeline
+
+__all__ = ["run_pipeline"]

agents/classifier.py

@@ -0,0 +1,72 @@
+"""Agent 2: Classifier — assigns clause types and detects contract type."""
+
+import json
+import logging
+from typing import Any
+
+from clauseguard.config.prompts import CLASSIFIER_SYSTEM_PROMPT
+from clauseguard.models.clause import Clause, ClauseList, ClauseType
+from clauseguard.services.model_service import call_model, clean_json_response
+
+logger = logging.getLogger(__name__)
+MAX_RETRIES = 1
+
+
+async def run_classifier(clause_list: ClauseList) -> ClauseList:
+    """Classify each clause and detect the overall contract type.
+
+    Args:
+        clause_list: The ClauseList from the Extractor agent.
+
+    Returns:
+        An updated ClauseList with clause_type and contract_type filled in.
+    """
+    input_json = clause_list.model_dump_json(indent=2)
+
+    content = await call_model(
+        system_prompt=CLASSIFIER_SYSTEM_PROMPT,
+        user_prompt=f"Classify these clauses:\n{input_json}",
+        agent_name="Classifier",
+        max_retries=MAX_RETRIES,
+    )
+
+    if content is None:
+        logger.warning("Classifier produced no valid output, returning original clauses")
+        return clause_list
+
+    return _parse_response(content, clause_list)
+
+
+def _parse_response(content: str, original: ClauseList) -> ClauseList:
+    """Parse the classifier JSON response and merge with original data."""
+    cleaned = clean_json_response(content)
+    data = json.loads(cleaned)
+
+    clauses_data = data.get("clauses", data if isinstance(data, list) else [])
+    contract_type = data.get("contract_type", "Other")
+
+    classified_clauses: list[Clause] = []
+    for c in clauses_data:
+        clause_type_raw = c.get("clause_type", "OTHER")
+        try:
+            clause_type = ClauseType(clause_type_raw)
+        except ValueError:
+            clause_type = ClauseType.OTHER
+
+        classified_clauses.append(
+            Clause(
+                id=c.get("id", 0),
+                raw_text=c.get("raw_text", ""),
+                plain_english=c.get("plain_english"),
+                clause_type=clause_type,
+                section_heading=c.get("section_heading"),
+                position=c.get("position", 0),
+                confidence_score=c.get("confidence_score"),
+            )
+        )
+
+    return ClauseList(
+        clauses=classified_clauses,
+        contract_type=contract_type,
+        total_clauses=len(classified_clauses),
+    )

agents/copilot.py

@@ -0,0 +1,165 @@
+"""ClauseGuard Copilot Agent — interactive AI chat assistant for contract analysis.
+
+This agent handles multi-turn conversations where users ask questions about
+their analyzed contract. It uses the full contract text and the completed
+clause analysis report as context, and responds via the Qwen model.
+"""
+
+import asyncio
+import logging
+from typing import Any, Dict, List
+
+from clauseguard.config.copilot_prompts import COPILOT_SYSTEM_PROMPT
+from clauseguard.models.report import FinalReport
+from clauseguard.services.model_service import call_model_chat
+
+logger = logging.getLogger(__name__)
+
+CHAT_TIMEOUT_SECONDS = 60
+
+
+def build_contract_context(full_contract_text: str, report: FinalReport) -> str:
+    """Build a detailed context string from the contract and its analysis.
+
+    This context is injected into every copilot conversation so the AI can
+    reference specific clauses, severity levels, and recommended fixes.
+
+    Args:
+        full_contract_text: The raw text of the original contract.
+        report: The completed FinalReport from the analysis pipeline.
+
+    Returns:
+        A formatted context string for the copilot.
+    """
+    parts: List[str] = []
+    parts.append("=" * 60)
+    parts.append("FULL CONTRACT TEXT")
+    parts.append("=" * 60)
+    parts.append(full_contract_text)
+    parts.append("")
+
+    parts.append("=" * 60)
+    parts.append("CLAUSE-BY-CLAUSE ANALYSIS")
+    parts.append("=" * 60)
+    parts.append(
+        f"Contract Type: {report.summary.contract_type} | "
+        f"Total Clauses: {report.summary.total_clauses} | "
+        f"Risk Score: {report.summary.overall_score}/10"
+    )
+    parts.append(
+        f"Critical: {report.summary.critical_count} | "
+        f"High: {report.summary.high_count} | "
+        f"Medium: {report.summary.medium_count} | "
+        f"Low: {report.summary.low_count}"
+    )
+    parts.append("")
+
+    for i, sc in enumerate(report.scored_clauses, 1):
+        parts.append(f"--- Clause {i} ---")
+        parts.append(f"Original Text: {sc.clause.raw_text}")
+        parts.append(f"Clause Type: {sc.clause.clause_type.value}")
+        if sc.clause.section_heading:
+            parts.append(f"Section: {sc.clause.section_heading}")
+        parts.append(f"Severity: {sc.finding.severity.value}")
+        parts.append(f"Risk Title: {sc.finding.risk_title}")
+        parts.append(f"Risk Reason: {sc.finding.risk_reason}")
+        if sc.clause.plain_english:
+            parts.append(f"Plain English: {sc.clause.plain_english}")
+        if sc.finding.recommended_action:
+            parts.append(f"Recommended Action: {sc.finding.recommended_action}")
+        if sc.finding.safer_clause_version:
+            parts.append(f"Safer Wording: {sc.finding.safer_clause_version}")
+        if sc.finding.negotiation_message:
+            parts.append(f"Negotiation Message: {sc.finding.negotiation_message}")
+        if sc.finding.impact_scenarios:
+            parts.append("Impact Scenarios:")
+            for impact in sc.finding.impact_scenarios:
+                parts.append(f"  - {impact}")
+        parts.append("")
+
+    if report.top_3_actions:
+        parts.append("=" * 60)
+        parts.append("TOP 3 RECOMMENDED ACTIONS")
+        parts.append("=" * 60)
+        for j, action in enumerate(report.top_3_actions, 1):
+            parts.append(f"{j}. {action}")
+        parts.append("")
+
+    return "\n".join(parts)
+
+
+def build_chat_messages(
+    system_prompt: str,
+    contract_context: str,
+    chat_history: List[Dict[str, str]],
+    user_message: str,
+) -> List[Dict[str, str]]:
+    """Build the full message list for the copilot chat API call.
+
+    Args:
+        system_prompt: The copilot system prompt.
+        contract_context: The formatted contract + analysis context.
+        chat_history: Previous messages in the conversation.
+        user_message: The new user message to respond to.
+
+    Returns:
+        A list of message dicts ready for the OpenAI chat API.
+    """
+    full_system = f"{system_prompt}\n\n---\n\n## CONTRACT CONTEXT\n\n{contract_context}"
+
+    messages: List[Dict[str, str]] = [
+        {"role": "system", "content": full_system},
+    ]
+
+    for msg in chat_history:
+        messages.append({"role": msg["role"], "content": msg["content"]})
+
+    messages.append({"role": "user", "content": user_message})
+
+    return messages
+
+
+async def run_copilot(
+    contract_context: str,
+    chat_history: List[Dict[str, str]],
+    user_message: str,
+) -> str:
+    """Send a user message to the copilot and return the assistant's response.
+
+    Args:
+        contract_context: The formatted contract + analysis context string.
+        chat_history: Previous messages in the conversation (role/content dicts).
+        user_message: The new question from the user.
+
+    Returns:
+        The assistant's text response, or an error message on failure.
+    """
+    messages = build_chat_messages(COPILOT_SYSTEM_PROMPT, contract_context, chat_history, user_message)
+    return await call_model_chat(messages, timeout=CHAT_TIMEOUT_SECONDS)
+
+
+# ── Python 3.10+ compat: same function available as synchronous wrapper for Streamlit ──
+
+def run_copilot_sync(
+    contract_context: str,
+    chat_history: List[Dict[str, str]],
+    user_message: str,
+) -> str:
+    """Synchronous wrapper around run_copilot for use in Streamlit callbacks.
+
+    Streamlit's chat input callback runs in the main thread, so we launch
+    a fresh event loop to run the async copilot call.
+    """
+    try:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        try:
+            result = loop.run_until_complete(
+                run_copilot(contract_context, chat_history, user_message)
+            )
+        finally:
+            loop.close()
+        return result
+    except Exception as e:
+        logger.error("run_copilot_sync failed: %s", e)
+        return f"Sorry, an unexpected error occurred: {e}"

agents/extractor.py

@@ -0,0 +1,104 @@
+"""Agent 1: Extractor — segments document into individual clauses."""
+
+import json
+import logging
+from typing import Optional
+
+from clauseguard.config.prompts import EXTRACTOR_SYSTEM_PROMPT
+from clauseguard.models.clause import Clause, ClauseList
+from clauseguard.services.model_service import call_model, clean_json_response
+
+logger = logging.getLogger(__name__)
+
+MIN_CLAUSES = 3
+MAX_RETRIES = 1
+
+
+async def run_extractor(raw_text: str, filename: str = "document") -> ClauseList:
+    """Extract clauses from raw contract text using the Extractor agent.
+
+    Args:
+        raw_text: The raw text content of the contract.
+        filename: Name of the source file (for context).
+
+    Returns:
+        A ClauseList containing the extracted clauses.
+
+    Raises:
+        ValueError: If fewer than MIN_CLAUSES clauses are found.
+    """
+    if not raw_text or not raw_text.strip():
+        raise ValueError("Document is empty or unreadable")
+
+    prompt = _build_user_prompt(raw_text, filename)
+
+    content = await call_model(
+        system_prompt=EXTRACTOR_SYSTEM_PROMPT,
+        user_prompt=prompt,
+        agent_name="Extractor",
+        max_retries=MAX_RETRIES,
+    )
+
+    if content is None:
+        raise ValueError("Extractor agent failed to produce a valid response")
+
+    clause_list = _parse_response(content)
+    _validate_clause_list(clause_list)
+    return clause_list
+
+
+def _build_user_prompt(raw_text: str, filename: str) -> str:
+    """Build the user prompt with the contract text."""
+    return f"""Extract all clauses from the following contract document.
+
+Filename: {filename}
+
+Document text:
+{raw_text}
+"""
+
+
+def _parse_response(content: str) -> ClauseList:
+    """Parse the LLM JSON response into a ClauseList."""
+    cleaned = clean_json_response(content)
+    data = json.loads(cleaned)
+
+    if isinstance(data, list):
+        clauses_data = data
+    elif isinstance(data, dict):
+        clauses_data = data.get("clauses", [])
+    else:
+        clauses_data = []
+
+    clauses: list[Clause] = []
+    for c in clauses_data:
+        clauses.append(
+            Clause(
+                id=c.get("id", 0),
+                raw_text=c.get("raw_text", ""),
+                plain_english=c.get("plain_english"),
+                clause_type=c.get("clause_type", "OTHER"),
+                section_heading=c.get("section_heading"),
+                position=c.get("position", 0),
+            )
+        )
+
+    contract_type_raw = data.get("contract_type", "Other") if isinstance(data, dict) else "Other"
+
+    return ClauseList(
+        clauses=clauses,
+        contract_type=contract_type_raw,
+        total_clauses=len(clauses),
+    )
+
+
+def _validate_clause_list(clause_list: ClauseList) -> None:
+    """Validate the extracted clause list meets minimum requirements.
+
+    Raises:
+        ValueError: If fewer than MIN_CLAUSES clauses are found.
+    """
+    if clause_list.total_clauses < MIN_CLAUSES:
+        raise ValueError(
+            f"Document too short or unreadable — minimum {MIN_CLAUSES} clauses required"
+        )

agents/orchestrator.py

@@ -0,0 +1,307 @@
+"""Orchestrator — manages the full 5-agent pipeline with OpenAI Agents SDK handoff."""
+
+import asyncio
+import logging
+from typing import Any, Callable, List
+
+try:
+    from agents import Agent as SdkAgent
+    from agents import Runner as SdkRunner
+
+    _SDK_AVAILABLE = True
+except ImportError:
+    _SDK_AVAILABLE = False
+
+from clauseguard.agents.classifier import run_classifier
+from clauseguard.agents.extractor import run_extractor
+from clauseguard.agents.reporter import run_reporter
+from clauseguard.agents.risk_scorer import run_risk_scorer
+from clauseguard.agents.translator import run_translator
+from clauseguard.config.settings import MAX_CLAUSES, TIMEOUT_SECONDS
+from clauseguard.models.clause import ClauseList
+from clauseguard.models.findings import ScoredClause
+from clauseguard.models.report import FinalReport
+
+# ── Live Agent Event System ──
+# The orchestrator emits events via a callback so the UI can show live status.
+# Default is a no-op; the UI replaces it with a Streamlit-aware callback at runtime.
+
+_live_event_callback: Callable[[str, str, dict[str, Any]], None] = lambda agent, status, details: None
+
+
+def set_event_callback(cb: Callable[[str, str, dict[str, Any]], None]) -> None:
+    """Register a callback for live agent events (called by the UI).
+
+    Args:
+        cb: Function receiving (agent_name, status, details_dict).
+            status is one of: 'running', 'completed', 'failed'.
+            details may contain 'message', 'clause_count', 'severity_counts', etc.
+    """
+    global _live_event_callback
+    _live_event_callback = cb
+
+
+def _emit(agent: str, status: str, **details: Any) -> None:
+    """Emit a live event for the given agent."""
+    try:
+        _live_event_callback(agent, status, details)
+    except Exception:
+        pass
+
+
+logger = logging.getLogger(__name__)
+
+
+async def run_pipeline(file_content: str, filename: str) -> FinalReport:
+    """Execute the full 5-agent pipeline on contract text.
+
+    Pipeline: Extractor -> Classifier -> Risk Scorer -> Translator -> Reporter
+
+    Uses OpenAI Agents SDK handoff() for agent orchestration when available.
+    Each agent call is wrapped in try/except with timeout.
+    If an agent fails, the pipeline continues with partial data.
+    Reporter always runs and returns a FinalReport.
+
+    Args:
+        file_content: The extracted text content of the contract.
+        filename: Name of the contract file (used in the report).
+
+    Returns:
+        A FinalReport containing the full risk analysis. Never raises.
+    """
+    clause_list: ClauseList = ClauseList()
+    scored_clauses: List[ScoredClause] = []
+    partial = False
+    truncation_note = ""
+
+    if _SDK_AVAILABLE:
+        logger.info("OpenAI Agents SDK handoff pipeline active")
+        result = await _run_sdk_pipeline(file_content, filename)
+        if result is not None:
+            return result
+
+    clause_list = await _step_extract(file_content, filename)
+    if clause_list.total_clauses > 0:
+        truncation_note = _check_truncation(clause_list, file_content)
+        if clause_list.total_clauses >= MAX_CLAUSES:
+            logger.warning("Document truncated to %d clauses (max %d)", clause_list.total_clauses, MAX_CLAUSES)
+
+        clause_list = await _step_classify(clause_list)
+        scored_clauses = await _step_risk_score(clause_list)
+        if scored_clauses:
+            scored_clauses = await _step_translate(scored_clauses)
+        else:
+            partial = True
+            logger.warning("Risk scorer produced no results — using fallback severity (MEDIUM) for all clauses")
+            scored_clauses = _build_fallback_scored_clauses(clause_list)
+            if scored_clauses:
+                scored_clauses = await _step_translate(scored_clauses)
+    else:
+        partial = True
+
+    contract_type = clause_list.contract_type if clause_list.contract_type else "Other"
+    return await _step_report(scored_clauses, filename, contract_type, partial, truncation_note)
+
+
+async def _run_sdk_pipeline(file_content: str, filename: str) -> FinalReport | None:
+    """Run the pipeline using OpenAI Agents SDK for handoff demonstration.
+
+    Handoff chain: Extractor -> Classifier -> Risk Scorer -> Translator -> Reporter
+    Returns None if SDK pipeline cannot complete, triggering fallback to direct calls.
+    """
+    try:
+        from clauseguard.config.prompts import (
+            CLASSIFIER_SYSTEM_PROMPT,
+            EXTRACTOR_SYSTEM_PROMPT,
+            REPORTER_SYSTEM_PROMPT,
+            RISK_SCORER_SYSTEM_PROMPT,
+            TRANSLATOR_SYSTEM_PROMPT,
+        )
+        from clauseguard.config.settings import MODEL_NAME
+
+        extractor_agent = SdkAgent(
+            name="Contract Extractor",
+            instructions=EXTRACTOR_SYSTEM_PROMPT,
+            model=MODEL_NAME,
+        )
+        classifier_agent = SdkAgent(
+            name="Clause Classifier",
+            instructions=CLASSIFIER_SYSTEM_PROMPT,
+            model=MODEL_NAME,
+        )
+        risk_scorer_agent = SdkAgent(
+            name="Risk Scorer",
+            instructions=RISK_SCORER_SYSTEM_PROMPT,
+            model=MODEL_NAME,
+        )
+        translator_agent = SdkAgent(
+            name="Plain English Translator",
+            instructions=TRANSLATOR_SYSTEM_PROMPT,
+            model=MODEL_NAME,
+        )
+        reporter_agent = SdkAgent(
+            name="Report Compiler",
+            instructions=REPORTER_SYSTEM_PROMPT,
+            model=MODEL_NAME,
+        )
+
+        extractor_agent.handoffs = [classifier_agent]
+        classifier_agent.handoffs = [risk_scorer_agent]
+        risk_scorer_agent.handoffs = [translator_agent]
+        translator_agent.handoffs = [reporter_agent]
+
+        logger.info("SDK handoff chain: Extractor -> Classifier -> Risk Scorer -> Translator -> Reporter")
+        result = await SdkRunner.run(
+            extractor_agent,
+            f"Extract all clauses from this contract file '{filename}':\n\n{file_content}",
+        )
+        logger.info("SDK pipeline completed with %d steps", len(result.new_items) if result else 0)
+    except Exception as e:
+        logger.warning("SDK handoff pipeline not fully available, falling back to direct calls: %s", e)
+
+    return None
+
+
+def _check_truncation(clause_list: ClauseList, original_text: str) -> str:
+    """Check if the document was truncated due to size limits."""
+    if clause_list.total_clauses >= MAX_CLAUSES:
+        word_count = len(original_text.split())
+        return (
+            f"Document exceeded maximum clause limit ({MAX_CLAUSES}). "
+            f"Only the first ~{MAX_CLAUSES} clauses were processed from a document "
+            f"of approximately {word_count} words. Some clauses may not appear in this report."
+        )
+    return ""
+
+
+def _build_fallback_scored_clauses(clause_list: ClauseList) -> List[ScoredClause]:
+    """Build scored clauses with MEDIUM severity when the risk scorer fails.
+
+    This ensures users still see their clauses in the report even when the AI
+    risk analysis could not complete, rather than showing 'no issues' misleadingly.
+    """
+    from clauseguard.models.findings import RiskFinding, ScoredClause, Severity
+
+    fallback: List[ScoredClause] = []
+    for clause in clause_list.clauses:
+        finding = RiskFinding(
+            clause_id=clause.id,
+            severity=Severity.MEDIUM,
+            risk_title="Needs Human Review",
+            risk_reason=(
+                f"The automated risk analyzer could not evaluate this clause. "
+                f"Type: {clause.clause_type.value}. "
+                f"Please review manually or consult legal counsel."
+            ),
+            recommended_action="Review this clause manually — the AI risk scorer could not complete.",
+        )
+        fallback.append(ScoredClause(clause=clause, finding=finding))
+    return fallback
+
+
+async def _step_extract(file_content: str, filename: str) -> ClauseList:
+    """Run the Extractor agent with error handling and timeout."""
+    try:
+        logger.info("Extracting clauses from document...")
+        _emit("Extractor", "running", message="Segmenting document into individual clauses")
+        result = await asyncio.wait_for(
+            run_extractor(file_content, filename),
+            timeout=TIMEOUT_SECONDS,
+        )
+        _emit("Extractor", "completed", message=f"Found {result.total_clauses} clauses", clause_count=result.total_clauses)
+        return result
+    except asyncio.TimeoutError:
+        _emit("Extractor", "failed", message="Timed out")
+        logger.error("Extractor agent timed out after %ds", TIMEOUT_SECONDS)
+        return ClauseList()
+    except Exception as e:
+        _emit("Extractor", "failed", message=str(e)[:80])
+        logger.error("Extractor agent failed: %s", e)
+        return ClauseList()
+
+
+async def _step_classify(clause_list: ClauseList) -> ClauseList:
+    """Run the Classifier agent with error handling and timeout."""
+    try:
+        logger.info("Classifying %d clauses...", clause_list.total_clauses)
+        _emit("Classifier", "running", message=f"Labeling {clause_list.total_clauses} clauses by type")
+        result = await asyncio.wait_for(
+            run_classifier(clause_list),
+            timeout=TIMEOUT_SECONDS,
+        )
+        _emit("Classifier", "completed", message=f"Detected contract type: {result.contract_type}")
+        return result
+    except asyncio.TimeoutError:
+        _emit("Classifier", "failed", message="Timed out")
+        logger.error("Classifier agent timed out")
+        return clause_list
+    except Exception as e:
+        _emit("Classifier", "failed", message=str(e)[:80])
+        logger.error("Classifier agent failed: %s", e)
+        return clause_list
+
+
+async def _step_risk_score(clause_list: ClauseList) -> List[ScoredClause]:
+    """Run the Risk Scorer agent with error handling and timeout."""
+    try:
+        logger.info("Scoring risks for %d clauses...", clause_list.total_clauses)
+        _emit("Risk Scorer", "running", message=f"Evaluating severity for {clause_list.total_clauses} clauses")
+        result = await asyncio.wait_for(
+            run_risk_scorer(clause_list),
+            timeout=TIMEOUT_SECONDS,
+        )
+        crit = sum(1 for s in result if s.finding.severity.value == "CRITICAL")
+        high = sum(1 for s in result if s.finding.severity.value == "HIGH")
+        _emit("Risk Scorer", "completed",
+              message=f"Found {crit} critical, {high} high-risk clauses",
+              severity_counts={"critical": crit, "high": high})
+        return result
+    except asyncio.TimeoutError:
+        _emit("Risk Scorer", "failed", message="Timed out")
+        logger.error("Risk Scorer agent timed out")
+        return []
+    except Exception as e:
+        _emit("Risk Scorer", "failed", message=str(e)[:80])
+        logger.error("Risk Scorer agent failed: %s", e)
+        return []
+
+
+async def _step_translate(scored_clauses: List[ScoredClause]) -> List[ScoredClause]:
+    """Run the Translator agent with error handling and timeout."""
+    try:
+        logger.info("Translating %d clauses to plain English...", len(scored_clauses))
+        _emit("Translator", "running", message=f"Writing plain-English versions + negotiation tips for {len(scored_clauses)} clauses")
+        result = await asyncio.wait_for(
+            run_translator(scored_clauses),
+            timeout=TIMEOUT_SECONDS,
+        )
+        _emit("Translator", "completed", message="Plain English translations ready")
+        return result
+    except asyncio.TimeoutError:
+        _emit("Translator", "failed", message="Timed out")
+        logger.error("Translator agent timed out")
+        return scored_clauses
+    except Exception as e:
+        _emit("Translator", "failed", message=str(e)[:80])
+        logger.error("Translator agent failed: %s", e)
+        return scored_clauses
+
+
+async def _step_report(
+    scored_clauses: List[ScoredClause],
+    filename: str,
+    contract_type: str,
+    partial: bool = False,
+    truncation_note: str = "",
+) -> FinalReport:
+    """Run the Reporter agent with error handling. No outer timeout — internal timeouts handle LLM calls."""
+    try:
+        logger.info("Building final report...")
+        _emit("Reporter", "running", message="Compiling final risk report")
+        result = await run_reporter(scored_clauses, filename, contract_type, partial, truncation_note)
+        _emit("Reporter", "completed", message=f"Report ready — score: {result.summary.overall_score}/10")
+        return result
+    except Exception as e:
+        _emit("Reporter", "failed", message=str(e)[:80])
+        logger.error("Reporter agent failed: %s", e)
+        return FinalReport(contract_name=filename, processed_normally=False)

agents/reporter.py

@@ -0,0 +1,205 @@
+"""Agent 5: Reporter — compiles the final risk report."""
+
+import json
+import logging
+from datetime import datetime
+from typing import List
+
+from clauseguard.config.prompts import REPORTER_SYSTEM_PROMPT
+from clauseguard.config.settings import MODEL_NAME, TEMPERATURE
+from clauseguard.models.findings import ScoredClause, Severity
+from clauseguard.models.report import FinalReport, RiskSummary
+from clauseguard.services.model_service import call_model, clean_json_response
+
+logger = logging.getLogger(__name__)
+MAX_RETRIES = 1
+
+
+async def run_reporter(
+    scored_clauses: List[ScoredClause],
+    contract_name: str,
+    contract_type: str,
+    partial: bool = False,
+    truncation_note: str = "",
+) -> FinalReport:
+    """Compile all analysis into a structured FinalReport.
+
+    Args:
+        scored_clauses: All scored clauses with risk findings.
+        contract_name: Name of the source contract file.
+        contract_type: Detected type of the contract.
+        partial: Whether this is a partial report due to agent failures.
+        truncation_note: Note about document truncation if contract exceeded clause limit.
+
+    Returns:
+        A complete FinalReport with summary, actions, and markdown.
+    """
+    sorted_clauses = _sort_by_severity(scored_clauses)
+    summary = _build_summary(sorted_clauses, contract_type)
+    top_3 = _extract_top_actions(sorted_clauses)
+
+    markdown = _build_markdown_programmatically(
+        sorted_clauses, contract_name, contract_type, summary, top_3
+    )
+
+    return FinalReport(
+        contract_name=contract_name,
+        generated_at=datetime.now(),
+        summary=summary,
+        top_3_actions=top_3,
+        scored_clauses=sorted_clauses,
+        markdown_report=markdown,
+        processed_normally=not partial,
+        truncation_note=truncation_note,
+    )
+
+
+def _sort_by_severity(scored_clauses: List[ScoredClause]) -> List[ScoredClause]:
+    """Sort scored clauses by severity (CRITICAL first)."""
+    severity_order = {Severity.CRITICAL: 0, Severity.HIGH: 1, Severity.MEDIUM: 2, Severity.LOW: 3, Severity.INFO: 4}
+    return sorted(scored_clauses, key=lambda sc: severity_order.get(sc.finding.severity, 99))
+
+
+def _build_summary(scored_clauses: List[ScoredClause], contract_type: str) -> RiskSummary:
+    """Build risk summary statistics from scored clauses."""
+    counts = {Severity.CRITICAL: 0, Severity.HIGH: 0, Severity.MEDIUM: 0, Severity.LOW: 0, Severity.INFO: 0}
+    for sc in scored_clauses:
+        counts[sc.finding.severity] = counts.get(sc.finding.severity, 0) + 1
+
+    total = len(scored_clauses)
+    if total > 0:
+        raw_score = (
+            counts[Severity.CRITICAL] * 10
+            + counts[Severity.HIGH] * 7
+            + counts[Severity.MEDIUM] * 4
+            + counts[Severity.LOW] * 1
+        ) / total
+        overall_score = round(min(raw_score, 10.0), 1)
+    else:
+        overall_score = 0.0
+
+    return RiskSummary(
+        total_clauses=total,
+        critical_count=counts[Severity.CRITICAL],
+        high_count=counts[Severity.HIGH],
+        medium_count=counts[Severity.MEDIUM],
+        low_count=counts[Severity.LOW],
+        overall_score=overall_score,
+        contract_type=contract_type,
+    )
+
+
+def _extract_top_actions(scored_clauses: List[ScoredClause]) -> List[str]:
+    """Extract the top 3 most impactful recommended actions."""
+    actions: List[str] = []
+    severity_priority = [Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM, Severity.LOW, Severity.INFO]
+
+    for sev in severity_priority:
+        for sc in scored_clauses:
+            if sc.finding.severity == sev and sc.finding.recommended_action:
+                if sc.finding.recommended_action not in actions:
+                    actions.append(sc.finding.recommended_action)
+                if len(actions) >= 3:
+                    return actions
+
+    if not actions:
+        actions.append("Review all clauses with legal counsel before signing.")
+
+    return actions[:3]
+
+
+def _build_markdown_programmatically(
+    scored_clauses: List[ScoredClause],
+    contract_name: str,
+    contract_type: str,
+    summary: RiskSummary,
+    top_3: List[str],
+) -> str:
+    """Build the markdown report programmatically."""
+    generated_str = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+    lines: List[str] = [
+        "# ClauseGuard Risk Report",
+        f"**Contract:** {contract_name}",
+        f"**Type:** {contract_type}",
+        f"**Overall Risk Score:** {summary.overall_score}/10",
+        f"**Generated:** {generated_str}",
+        "",
+        "---",
+        "",
+        "## Executive Summary",
+        _build_executive_summary_text(scored_clauses, summary),
+        "",
+        "## Top 3 Actions Before Signing",
+    ]
+
+    for i, action in enumerate(top_3, 1):
+        lines.append(f"{i}. {action}")
+
+    info_count = summary.total_clauses - summary.critical_count - summary.high_count - summary.medium_count - summary.low_count
+
+    lines.extend([
+        "",
+        "## Risk Summary",
+        "| Severity | Count |",
+        "|----------|-------|",
+        f"| 🔴 Critical | {summary.critical_count} |",
+        f"| 🟠 High | {summary.high_count} |",
+        f"| 🟡 Medium | {summary.medium_count} |",
+        f"| 🟢 Low | {summary.low_count} |",
+        f"| ℹ️ Info | {max(info_count, 0)} |",
+        "",
+        "---",
+        "",
+        "## Clause Analysis",
+        "",
+    ])
+
+    for sc in scored_clauses:
+        emoji = _severity_emoji(sc.finding.severity)
+        lines.append(
+            f"### {sc.clause.clause_type.value} — {emoji} {sc.finding.severity.value}"
+        )
+        lines.append(f"**Original:** {sc.clause.raw_text}")
+        if sc.clause.plain_english:
+            lines.append(f"**Plain English:** {sc.clause.plain_english}")
+        lines.append(f"**Risk:** {sc.finding.risk_reason}")
+        if sc.finding.recommended_action:
+            lines.append(f"**Action:** {sc.finding.recommended_action}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def _build_executive_summary_text(
+    scored_clauses: List[ScoredClause], summary: RiskSummary
+) -> str:
+    """Build a brief executive summary of the main risks."""
+    high_severity = [sc for sc in scored_clauses if sc.finding.severity in (Severity.CRITICAL, Severity.HIGH)]
+
+    if not high_severity:
+        return (
+            "This contract appears to be reasonably balanced with no critical or high-risk clauses identified. "
+            "Review the medium-risk findings below for items that may warrant attention."
+        )
+
+    types_found = list({sc.clause.clause_type.value for sc in high_severity})
+    types_str = ", ".join(types_found)
+
+    return (
+        f"This contract contains {summary.critical_count} critical and {summary.high_count} high-severity risks "
+        f"that require immediate attention. The most concerning areas involve: {types_str}. "
+        f"We strongly recommend addressing the top 3 actions below before signing this agreement."
+    )
+
+
+def _severity_emoji(severity: Severity) -> str:
+    """Return emoji for severity level."""
+    emoji_map = {
+        Severity.CRITICAL: "🔴",
+        Severity.HIGH: "🟠",
+        Severity.MEDIUM: "🟡",
+        Severity.LOW: "🟢",
+        Severity.INFO: "ℹ️",
+    }
+    return emoji_map.get(severity, "⚪")

agents/risk_scorer.py

@@ -0,0 +1,86 @@
+"""Agent 3: Risk Scorer — evaluates severity of each clause."""
+
+import json
+import logging
+from typing import List
+
+from clauseguard.config.prompts import RISK_SCORER_SYSTEM_PROMPT
+from clauseguard.models.clause import Clause, ClauseType
+from clauseguard.models.findings import RiskFinding, ScoredClause, Severity
+from clauseguard.services.model_service import call_model, clean_json_response
+
+logger = logging.getLogger(__name__)
+MAX_RETRIES = 1
+
+
+async def run_risk_scorer(clause_list) -> List[ScoredClause]:
+    """Evaluate each clause and assign severity with evidence-based risk reasons.
+
+    Args:
+        clause_list: A ClauseList with classified clauses.
+
+    Returns:
+        A list of ScoredClause objects with risk findings.
+    """
+    input_json = clause_list.model_dump_json(indent=2)
+
+    content = await call_model(
+        system_prompt=RISK_SCORER_SYSTEM_PROMPT,
+        user_prompt=f"Score the risk for each of these clauses:\n{input_json}",
+        agent_name="Risk Scorer",
+        max_retries=MAX_RETRIES,
+    )
+
+    if content is None:
+        logger.warning("Risk Scorer produced no valid output after retries")
+        return []
+
+    return _parse_response(content)
+
+
+def _parse_response(content: str) -> List[ScoredClause]:
+    """Parse the risk scorer JSON response into ScoredClause objects."""
+    cleaned = clean_json_response(content)
+    data = json.loads(cleaned)
+
+    scored_clauses: List[ScoredClause] = []
+    items = data if isinstance(data, list) else data.get("scored_clauses", [data])
+
+    for item in items:
+        clause_data = item.get("clause", {})
+        finding_data = item.get("finding", {})
+
+        clause_type_raw = clause_data.get("clause_type", "OTHER")
+        try:
+            clause_type = ClauseType(clause_type_raw)
+        except ValueError:
+            clause_type = ClauseType.OTHER
+
+        severity_raw = finding_data.get("severity", "INFO")
+        try:
+            severity = Severity(severity_raw)
+        except ValueError:
+            severity = Severity.INFO
+
+        clause = Clause(
+            id=clause_data.get("id", 0),
+            raw_text=clause_data.get("raw_text", ""),
+            plain_english=clause_data.get("plain_english"),
+            clause_type=clause_type,
+            section_heading=clause_data.get("section_heading"),
+            position=clause_data.get("position", 0),
+            confidence_score=clause_data.get("confidence_score"),
+        )
+
+        finding = RiskFinding(
+            clause_id=finding_data.get("clause_id", clause.id),
+            severity=severity,
+            risk_title=finding_data.get("risk_title", "Risk Identified"),
+            risk_reason=finding_data.get("risk_reason", ""),
+            recommended_action=finding_data.get("recommended_action", ""),
+            negotiation_tip=finding_data.get("negotiation_tip", ""),
+        )
+
+        scored_clauses.append(ScoredClause(clause=clause, finding=finding))
+
+    return scored_clauses

agents/translator.py

@@ -0,0 +1,123 @@
+"""Agent 4: Translator — writes plain English explanations and negotiation support."""
+
+import json
+import logging
+from typing import List
+
+from clauseguard.config.prompts import TRANSLATOR_SYSTEM_PROMPT
+from clauseguard.models.clause import Clause, ClauseType
+from clauseguard.models.findings import RiskFinding, ScoredClause, Severity
+from clauseguard.services.model_service import call_model, clean_json_response
+
+logger = logging.getLogger(__name__)
+MAX_RETRIES = 1
+
+
+async def run_translator(scored_clauses: List[ScoredClause]) -> List[ScoredClause]:
+    """Translate legal clauses into plain English and write actionable recommendations.
+
+    Args:
+        scored_clauses: A list of ScoredClause objects from the Risk Scorer.
+
+    Returns:
+        Updated ScoredClause list with plain_english and recommended_action filled in.
+    """
+    scored_json = [
+        {
+            "clause": sc.clause.model_dump(),
+            "finding": sc.finding.model_dump(),
+        }
+        for sc in scored_clauses
+    ]
+    input_json = json.dumps(scored_json, indent=2)
+
+    content = await call_model(
+        system_prompt=TRANSLATOR_SYSTEM_PROMPT,
+        user_prompt=f"Translate these clauses into plain English:\n{input_json}",
+        agent_name="Translator",
+        max_retries=MAX_RETRIES,
+    )
+
+    if content is None:
+        logger.warning("Translator produced no valid output, returning original clauses")
+        return scored_clauses
+
+    return _parse_response(content, scored_clauses)
+
+
+def _parse_response(content: str, original: List[ScoredClause]) -> List[ScoredClause]:
+    """Parse translator response and merge plain_english + actions into originals."""
+    cleaned = clean_json_response(content)
+    data = json.loads(cleaned)
+
+    items = data if isinstance(data, list) else [data]
+    result: List[ScoredClause] = []
+
+    for i, item in enumerate(items):
+        clause_data = item.get("clause", {})
+        finding_data = item.get("finding", {})
+
+        plain_english = clause_data.get("plain_english")
+        recommended_action = finding_data.get("recommended_action", "")
+        negotiation_tip = finding_data.get("negotiation_tip", "")
+        safer_clause_version = finding_data.get("safer_clause_version", "")
+        negotiation_message = finding_data.get("negotiation_message", "")
+        impact_scenarios = finding_data.get("impact_scenarios", [])
+
+        if i < len(original):
+            orig = original[i]
+            clause = orig.clause.model_copy(update={"plain_english": plain_english})
+            finding_updates = {"recommended_action": recommended_action}
+            if negotiation_tip:
+                finding_updates["negotiation_tip"] = negotiation_tip
+            if safer_clause_version:
+                finding_updates["safer_clause_version"] = safer_clause_version
+            if negotiation_message:
+                finding_updates["negotiation_message"] = negotiation_message
+            if impact_scenarios:
+                finding_updates["impact_scenarios"] = impact_scenarios
+            finding = orig.finding.model_copy(update=finding_updates)
+            result.append(ScoredClause(clause=clause, finding=finding))
+        else:
+            result.append(_build_scored_clause_from_data(clause_data, finding_data))
+
+    return result
+
+
+def _build_scored_clause_from_data(clause_data: dict, finding_data: dict) -> ScoredClause:
+    """Build a ScoredClause from raw LLM response data."""
+    clause_type_raw = clause_data.get("clause_type", "OTHER")
+    try:
+        clause_type = ClauseType(clause_type_raw)
+    except ValueError:
+        clause_type = ClauseType.OTHER
+
+    severity_raw = finding_data.get("severity", "INFO")
+    try:
+        severity = Severity(severity_raw)
+    except ValueError:
+        severity = Severity.INFO
+
+    clause = Clause(
+        id=clause_data.get("id", 0),
+        raw_text=clause_data.get("raw_text", ""),
+        plain_english=clause_data.get("plain_english"),
+        clause_type=clause_type,
+        section_heading=clause_data.get("section_heading"),
+        position=clause_data.get("position", 0),
+        confidence_score=clause_data.get("confidence_score"),
+    )
+
+    finding = RiskFinding(
+        clause_id=finding_data.get("clause_id", clause.id),
+        severity=severity,
+        risk_title=finding_data.get("risk_title", "Risk Identified"),
+        risk_reason=finding_data.get("risk_reason", ""),
+        recommended_action=finding_data.get("recommended_action", ""),
+        negotiation_tip=finding_data.get("negotiation_tip", ""),
+        safer_clause_version=finding_data.get("safer_clause_version", ""),
+        negotiation_message=finding_data.get("negotiation_message", ""),
+        impact_scenarios=finding_data.get("impact_scenarios", []),
+    )
+
+    return ScoredClause(clause=clause, finding=finding)

app.py

@@ -0,0 +1,1518 @@
+"""ClauseGuard Streamlit UI — redesigned modern SaaS edition."""
+import asyncio
+import logging
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import streamlit as st
+import pandas as pd
+
+from clauseguard.agents.copilot import build_contract_context, run_copilot_sync
+from clauseguard.agents.orchestrator import run_pipeline, set_event_callback
+from clauseguard.config.settings import validate_config
+from clauseguard.models.findings import RiskFinding, ScoredClause, Severity
+from clauseguard.models.report import FinalReport
+from clauseguard.tools.file_tools import extract_text
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# ── Constants ────────────────────────────────────────────────────────────────
+
+MAX_FILE_SIZE_MB = 10
+MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024
+ALLOWED_EXTENSIONS = ["pdf", "txt", "docx"]
+
+TAB_NAMES = ["📊  Overview", "📋  Clauses", "💬  Negotiation", "🤖  Chat Assistant"]
+TAB_SESSION_KEY = "tab_selector_radio"
+
+AGENT_NAMES = ["Extractor", "Classifier", "Risk Scorer", "Translator", "Reporter"]
+AGENT_ICONS = {"running": "⚙️", "completed": "✅", "failed": "❌", "pending": "⏳"}
+AGENT_STEP_NUMBERS = {"Extractor": "①", "Classifier": "②", "Risk Scorer": "③",
+                       "Translator": "④", "Reporter": "⑤"}
+
+SEVERITY_STYLE = {
+    Severity.CRITICAL: {"badge": "🔴 CRITICAL", "border": "#ff4444", "bg": "rgba(255,68,68,0.12)", "color": "#ff6666", "tag_bg": "rgba(255,68,68,0.18)"},
+    Severity.HIGH:     {"badge": "🟠 HIGH",     "border": "#ff8c00", "bg": "rgba(255,140,0,0.12)",  "color": "#ffaa44", "tag_bg": "rgba(255,140,0,0.15)"},
+    Severity.MEDIUM:   {"badge": "🟡 MEDIUM",   "border": "#ffd700", "bg": "rgba(255,215,0,0.12)",  "color": "#ffdd55", "tag_bg": "rgba(255,215,0,0.12)"},
+    Severity.LOW:      {"badge": "🟢 LOW",      "border": "#32cd32", "bg": "rgba(50,205,50,0.12)",   "color": "#55dd55", "tag_bg": "rgba(50,205,50,0.10)"},
+    Severity.INFO:     {"badge": "ℹ️ INFO",      "border": "#1e90ff", "bg": "rgba(30,144,255,0.08)",  "color": "#55aaff", "tag_bg": "rgba(30,144,255,0.08)"},
+}
+
+
+def _check_model_connectivity() -> tuple[bool, str]:
+    """Quick connectivity check against the configured model endpoint.
+
+    Returns:
+        (ok, error_message) — ok is True if the endpoint is reachable.
+    """
+    import asyncio
+    from clauseguard.services.model_service import get_client
+    from clauseguard.config.settings import MODEL_NAME
+
+    try:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        try:
+            client = get_client()
+            loop.run_until_complete(
+                asyncio.wait_for(
+                    client.models.list(),
+                    timeout=10,
+                )
+            )
+            return True, ""
+        except asyncio.TimeoutError:
+            return False, "Model endpoint timed out — the vLLM server may be offline or unreachable"
+        except Exception as e:
+            err = str(e)
+            if "ConnectionRefusedError" in err or "Connection refused" in err or "ConnectError" in err:
+                return False, f"Connection refused — vLLM server is not running at the configured BASE_URL"
+            if "Name or service not known" in err or "getaddrinfo" in err.lower():
+                return False, f"Cannot resolve host — check that the BASE_URL is correct"
+            return False, f"Model endpoint error: {err[:120]}"
+        finally:
+            loop.close()
+    except Exception as e:
+        return False, f"Connectivity check failed: {str(e)[:120]}"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# CUSTOM CSS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+CUSTOM_CSS = """
+<style>
+    .main .block-container { padding-top: 1.5rem; padding-bottom: 2rem; }
+    
+    .stButton > button {
+        border-radius: 10px;
+        font-weight: 600;
+        font-size: 0.95rem;
+        padding: 0.65rem 1.5rem;
+        transition: all 0.2s ease;
+        border: 1px solid rgba(255,255,255,0.08);
+    }
+    .stButton > button:hover {
+        transform: translateY(-1px);
+        box-shadow: 0 6px 20px rgba(102,126,234,0.35);
+    }
+    .stButton > button[kind="primary"] {
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
+        color: #fff !important;
+        border: none !important;
+    }
+    .stButton > button[kind="secondary"] {
+        background: rgba(255,255,255,0.06) !important;
+        color: #e0e0e0 !important;
+        border: 1px solid rgba(255,255,255,0.12) !important;
+    }
+    
+    .stFileUploader section {
+        border: 2px dashed #667eea !important;
+        border-radius: 14px !important;
+        padding: 1.5rem !important;
+        background: rgba(102,126,234,0.03) !important;
+        transition: all 0.25s ease;
+    }
+    .stFileUploader section:hover {
+        border-color: #8ab4f8 !important;
+        background: rgba(102,126,234,0.08) !important;
+    }
+    
+    div[role="radiogroup"] {
+        display: flex; gap: 4px;
+        background: #0e1117; padding: 4px;
+        border-radius: 14px; border: 1px solid rgba(255,255,255,0.06);
+        margin-bottom: 1rem;
+    }
+    div[role="radiogroup"] label {
+        flex: 1; text-align: center;
+        padding: 10px 16px !important;
+        border-radius: 10px;
+        font-weight: 600; font-size: 0.92rem;
+        color: #aaa; cursor: pointer;
+        transition: all 0.2s ease;
+    }
+    div[role="radiogroup"] label:hover { background: rgba(255,255,255,0.04); }
+    div[role="radiogroup"] label:has(input:checked) {
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
+        color: #ffffff !important;
+    }
+    div[role="radiogroup"] input[type="radio"] {
+        position: absolute; opacity: 0; width: 0; height: 0;
+    }
+    
+    @media (max-width: 768px) {
+        div[role="radiogroup"] label { padding: 8px 10px; font-size: 0.78rem; }
+    }
+    .stTabs [data-baseweb="tab"] {
+        font-weight: 600;
+        font-size: 0.95rem;
+        padding: 10px 20px;
+        border-radius: 10px;
+        color: #aaa;
+    }
+    .stTabs [aria-selected="true"] {
+        color: #ffffff !important;
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
+        border-radius: 10px !important;
+    }
+    
+    .stExpander {
+        border: 1px solid rgba(255,255,255,0.06) !important;
+        border-radius: 10px !important;
+        margin-bottom: 0.3rem !important;
+        overflow: hidden;
+        transition: all 0.15s ease;
+    }
+    .stExpander:hover {
+        border-color: rgba(255,255,255,0.1) !important;
+    }
+    .stExpander > div:first-child {
+        border-radius: 10px !important;
+        background: rgba(255,255,255,0.015);
+    }
+    
+    .stChatMessage { border-radius: 12px !important; }
+    
+    .stProgress > div > div > div > div {
+        background: linear-gradient(90deg, #667eea, #764ba2) !important;
+        border-radius: 4px;
+    }
+    
+    [data-testid="stMetric"] {
+        background: rgba(255,255,255,0.03);
+        border: 1px solid rgba(255,255,255,0.06);
+        border-radius: 12px;
+        padding: 0.75rem 1rem;
+    }
+    [data-testid="stMetric"] label { font-weight: 500 !important; }
+    
+    .stCodeBlock { border-radius: 10px !important; }
+    
+    .cg-card {
+        background: linear-gradient(145deg, #12121f 0%, #0e1117 100%);
+        border: 1px solid rgba(255,255,255,0.07);
+        border-radius: 14px;
+        padding: 1.25rem;
+        margin-bottom: 1rem;
+        transition: border-color 0.2s ease;
+    }
+    .cg-card:hover { border-color: rgba(255,255,255,0.12); }
+    
+    .cg-badge {
+        display: inline-block;
+        padding: 0.25rem 0.7rem;
+        border-radius: 20px;
+        font-size: 0.75rem;
+        font-weight: 700;
+        letter-spacing: 0.4px;
+        text-transform: uppercase;
+    }
+    
+    @keyframes pulse-glow {
+        0%, 100% { opacity: 1; }
+        50% { opacity: 0.6; }
+    }
+    .agent-running {
+        animation: pulse-glow 1.4s ease-in-out infinite;
+    }
+    
+    .cg-chip {
+        display: inline-block;
+        padding: 0.35rem 0.9rem;
+        border-radius: 20px;
+        font-size: 0.78rem;
+        font-weight: 500;
+        background: rgba(102,126,234,0.12);
+        color: #8ab4f8;
+        border: 1px solid rgba(102,126,234,0.2);
+        cursor: pointer;
+        margin: 0.2rem;
+        transition: all 0.15s ease;
+    }
+    .cg-chip:hover {
+        background: rgba(102,126,234,0.25);
+        border-color: rgba(102,126,234,0.4);
+    }
+    
+    @media (max-width: 768px) {
+        .stTabs [data-baseweb="tab"] { padding: 8px 12px; font-size: 0.8rem; }
+    }
+</style>
+"""
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# DEMO REPORT BUILDER
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def _build_demo_report() -> FinalReport:
+    """Build a pre-cached demo report with negotiation copilot content."""
+    from clauseguard.models.clause import Clause, ClauseType
+
+    demo_with_copilot: list[dict] = [
+        {
+            "text": "Recipient hereby irrevocably assigns to Company all inventions, discoveries, and intellectual property created during this Agreement and for 1 year after, regardless of whether created on Recipient's own time or equipment.",
+            "ctype": "IP_ASSIGNMENT", "sev": "CRITICAL",
+            "title": "IP Assignment of Personal Work",
+            "reason": "Claims ownership of ALL creations including personal projects on personal time and equipment, extending 1 year after termination.",
+            "plain": "You give the company ownership of everything you create — including personal side projects on your own time and equipment — for up to a year after you leave.",
+            "action": "Demand a carve-out for inventions created on your own time using your own equipment.",
+            "safer": "Employee assigns to Company all inventions directly related to Company's business and created during working hours using Company resources. Inventions created on Employee's own time using personal equipment, and unrelated to Company's business, remain the sole property of Employee.",
+            "negotiation": "Hi, I've reviewed the IP clause and would like to request an adjustment to ensure personal projects created outside work hours remain mine. I've suggested alternative wording below. Would you be open to this change? Thanks!",
+            "impacts": ["You may lose ownership of any side projects or startups you work on during employment", "The company could claim your open-source contributions made on weekends"],
+        },
+        {
+            "text": "All disputes shall be resolved exclusively through binding arbitration. The parties waive any right to a trial by jury and waive the right to participate in any class action.",
+            "ctype": "ARBITRATION", "sev": "CRITICAL",
+            "title": "Mandatory Arbitration with Jury + Class Action Waiver",
+            "reason": "Forces disputes into private arbitration, waives your constitutional right to a jury trial, and blocks class actions — all with no opt-out.",
+            "plain": "You give up your right to sue in court or join a class-action lawsuit. All disputes go through private arbitration instead.",
+            "action": "Add an opt-out clause for arbitration — preserve your right to go to court.",
+            "safer": "Either party may opt out of binding arbitration by providing written notice within 30 days of signing. Nothing in this section prevents participation in class actions where permitted by law.",
+            "negotiation": "Hi, I've reviewed the dispute resolution clause. I'd like to add an opt-out option for arbitration so both parties retain the right to choose their preferred forum. I've suggested language below. Does this work for you?",
+            "impacts": ["If the company violates your rights, you cannot sue them in a public court", "You cannot join with other affected parties in a class action — you must fight alone"],
+        },
+        {
+            "text": "For 18 months following termination, Recipient shall not engage in any business competitive with Company, anywhere in the world.",
+            "ctype": "NON_COMPETE", "sev": "HIGH",
+            "title": "Worldwide Non-Compete — 18 Months",
+            "reason": "18-month ban on working for ANY competitor worldwide with no geographic limitation tied to Company's actual operations.",
+            "plain": "You cannot work for any competitor anywhere in the world for 18 months after this agreement ends — even if the company doesn't operate in that region.",
+            "action": "Reduce duration to 12 months and limit scope to regions where Company actually does business.",
+            "safer": "For 12 months following termination, Recipient shall not provide services to direct competitors of Company within the specific metro areas where Company has active business operations.",
+            "negotiation": "Hi, the non-compete clause is quite broad — it covers the entire world for 18 months. I'd suggest narrowing the scope to 12 months within regions where the company actually operates. I've drafted alternative language below.",
+            "impacts": ["You may be unable to work in your industry anywhere in the world for 18 months after leaving", "Relocating to a new city won't help — the restriction is global"],
+        },
+        {
+            "text": "This Agreement shall automatically renew for successive 1-year terms unless either party provides written notice at least 90 days prior.",
+            "ctype": "AUTO_RENEWAL", "sev": "MEDIUM",
+            "title": "Auto-Renewal with 90-Day Notice",
+            "reason": "Auto-renews annually. 90-day notice period is longer than standard and easy to miss.",
+            "plain": "This agreement renews automatically every year. You must give 90 days written notice to cancel — miss the deadline and you're locked in.",
+            "action": "Reduce notice period to 30 days or request automatic email reminders.",
+            "safer": "", "negotiation": "", "impacts": [],
+        },
+        {
+            "text": "Recipient agrees to hold all Confidential Information in strict confidence.",
+            "ctype": "NDA", "sev": "LOW",
+            "title": "Standard Confidentiality Obligation",
+            "reason": "Standard NDA language requiring reasonable care — no unusual provisions.",
+            "plain": "You must keep the company's confidential information secret and only use it as authorized.",
+            "action": "No action needed — standard boilerplate.",
+            "safer": "", "negotiation": "", "impacts": [],
+        },
+        {
+            "text": "This Agreement shall be governed by the laws of the State of New York.",
+            "ctype": "GOVERNING_LAW", "sev": "LOW",
+            "title": "Standard Governing Law",
+            "reason": "Standard choice-of-law clause selecting New York — common in contracts.",
+            "plain": "This agreement is governed by New York law, and disputes must be handled in New York courts.",
+            "action": "No action needed unless you are far from New York.",
+            "safer": "", "negotiation": "", "impacts": [],
+        },
+        {
+            "text": "This Agreement constitutes the entire agreement between the parties.",
+            "ctype": "OTHER", "sev": "INFO",
+            "title": "Standard Entire Agreement Clause",
+            "reason": "Standard integration clause confirming this is the complete agreement.",
+            "plain": "This document is the complete and final agreement between you and the company.",
+            "action": "No action needed — standard boilerplate.",
+            "safer": "", "negotiation": "", "impacts": [],
+        },
+    ]
+
+    scored = []
+    for i, d in enumerate(demo_with_copilot, 1):
+        clause = Clause(id=i, raw_text=d["text"], plain_english=d["plain"],
+                        clause_type=ClauseType(d["ctype"]),
+                        section_heading=d["ctype"].replace("_", " "), position=i, confidence_score=0.95)
+        finding = RiskFinding(clause_id=i, severity=Severity(d["sev"]), risk_title=d["title"],
+                              risk_reason=d["reason"], recommended_action=d["action"],
+                              safer_clause_version=d["safer"], negotiation_message=d["negotiation"],
+                              impact_scenarios=d["impacts"])
+        scored.append(ScoredClause(clause=clause, finding=finding))
+
+    crit = sum(1 for s in scored if s.finding.severity == Severity.CRITICAL)
+    high = sum(1 for s in scored if s.finding.severity == Severity.HIGH)
+    med = sum(1 for s in scored if s.finding.severity == Severity.MEDIUM)
+    low = sum(1 for s in scored if s.finding.severity == Severity.LOW)
+    raw = (crit * 10 + high * 7 + med * 4 + low * 1) / len(scored)
+    overall = round(min(raw, 10.0), 1)
+
+    return FinalReport(
+        contract_name="sample_nda.txt (Demo)",
+        generated_at=datetime.now(),
+        summary={"total_clauses": len(scored), "critical_count": crit, "high_count": high,
+                 "medium_count": med, "low_count": low, "overall_score": overall, "contract_type": "NDA"},
+        top_3_actions=[
+            "Demand a carve-out for inventions created on your own time using your own equipment.",
+            "Add an opt-out clause for arbitration — preserve your right to go to court.",
+            "Reduce non-compete to 12 months with geographic scope tied to actual operations.",
+        ],
+        scored_clauses=scored,
+        markdown_report="""# ClauseGuard Risk Analysis Report
+**Contract:** sample_nda.txt
+**Generated:** {date}
+**Risk Score:** {score}/10
+**Contract Type:** NDA
+
+## Summary
+- Total Clauses: {total}
+- Critical: {crit}
+- High: {high}
+- Medium: {med}
+- Low: {low}
+
+## Top Actions
+1. Demand a carve-out for inventions created on your own time using your own equipment.
+2. Add an opt-out clause for arbitration — preserve your right to go to court.
+3. Reduce non-compete to 12 months with geographic scope tied to actual operations.
+
+---
+*Generated by ClauseGuard AI*
+""".format(date=datetime.now().strftime('%B %d, %Y'), score=overall, total=len(scored), crit=crit, high=high, med=med, low=low),
+        processed_normally=False,
+    )
+
+
+def _load_demo_report() -> None:
+    st.session_state.report = _build_demo_report()
+    st.session_state.error = None
+    st.session_state.uploaded_filename = "sample_nda.txt"
+    demo_raw = ""
+    for sc in st.session_state.report.scored_clauses:
+        heading = sc.clause.section_heading or ""
+        text = sc.clause.raw_text
+        demo_raw += f"{heading}\n{text}\n\n" if heading else f"{text}\n\n"
+    st.session_state.copilot_raw_text = demo_raw.strip()
+    st.session_state.active_tab = 0
+    st.session_state.copilot_messages = []
+    st.session_state.clause_ai_responses = {}
+    st.session_state.generated_emails = {}
+    st.session_state.copilot_cache_key = None
+    st.rerun()
+
+
+def _load_guided_demo() -> None:
+    st.session_state.guided_demo = True
+    st.session_state.demo_step = 0
+    _load_demo_report()
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# SESSION STATE
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def _init_session_state() -> None:
+    defaults = {
+        "report": None,
+        "error": None,
+        "analyzing": False,
+        "uploaded_filename": None,
+        "uploaded_bytes": None,
+        "agent_statuses": {a: "pending" for a in AGENT_NAMES},
+        "agent_messages": {a: "" for a in AGENT_NAMES},
+        "guided_demo": False,
+        "demo_step": 0,
+        "copilot_messages": [],
+        "copilot_context": "",
+        "copilot_raw_text": "",
+        "copilot_cache_key": None,
+        "clause_ai_responses": {},
+        "pending_ai_query": None,
+        "generated_emails": {},
+        "active_tab": 0,
+        "highlight_clause_id": None,
+    }
+    for key, default in defaults.items():
+        if key not in st.session_state:
+            st.session_state[key] = default
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# LIVE AGENT EVENT HANDLER
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def _on_agent_event(agent: str, status: str, details: dict) -> None:
+    st.session_state.agent_statuses[agent] = status
+    st.session_state.agent_messages[agent] = details.get("message", "")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# ANALYSIS RUNNER
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def _run_analysis() -> None:
+    file_bytes = st.session_state.uploaded_bytes
+    filename = st.session_state.uploaded_filename
+    try:
+        validate_config()
+    except ValueError as e:
+        st.session_state.error = str(e)
+        st.session_state.analyzing = False
+        return
+
+    for a in AGENT_NAMES:
+        st.session_state.agent_statuses[a] = "pending"
+        st.session_state.agent_messages[a] = ""
+
+    set_event_callback(_on_agent_event)
+
+    progress_bar = st.progress(0)
+    status_text = st.empty()
+    agent_panel = st.empty()
+
+    try:
+        status_text.markdown("<h3 style='color:#fff'>🔍 Reading file...</h3>", unsafe_allow_html=True)
+        raw_text = extract_text(file_bytes, filename)
+        st.session_state.copilot_raw_text = raw_text
+
+        status_text.markdown("<h3 style='color:#8ab4f8'>🔗 Testing model connection...</h3>", unsafe_allow_html=True)
+        ok, conn_err = _check_model_connectivity()
+        if not ok:
+            st.session_state.error = f"Cannot connect to model API: {conn_err}"
+            st.session_state.analyzing = False
+            progress_bar.empty()
+            status_text.empty()
+            agent_panel.empty()
+            st.rerun()
+            return
+
+        status_text.markdown("<h3 style='color:#8ab4f8'>🤖 Running AI analysis pipeline...</h3>", unsafe_allow_html=True)
+
+        def _render_agent_panel():
+            rows = ""
+            for a in AGENT_NAMES:
+                step = AGENT_STEP_NUMBERS.get(a, "")
+                s = st.session_state.agent_statuses[a]
+                icon = AGENT_ICONS.get(s, "⏳")
+                msg = st.session_state.agent_messages.get(a, "")
+                if s == "completed":
+                    color = "#55dd55"
+                    anim = ""
+                elif s == "failed":
+                    color = "#ff4444"
+                    anim = ""
+                elif s == "running":
+                    color = "#ffaa44"
+                    anim = " class='agent-running'"
+                else:
+                    color = "#666"
+                    anim = ""
+                rows += f"<tr{anim}><td style='padding:8px 12px;text-align:center;font-size:1.1rem'>{step}</td><td style='padding:8px 12px'>{icon}</td><td style='padding:8px 12px;color:{color};font-weight:600'>{a}</td><td style='padding:8px 12px;color:#aaa;font-size:0.85rem'>{msg}</td></tr>"
+            return f"<div style='background:#1a1a2e;border-radius:14px;padding:1.25rem;border:1px solid rgba(255,255,255,0.08)'><table style='width:100%;border-collapse:collapse'><thead><tr><th style='padding:6px 12px;color:#888;font-size:0.7rem;text-transform:uppercase;letter-spacing:1px'>Step</th><th style='padding:6px 12px'></th><th style='padding:6px 12px;color:#888;font-size:0.7rem;text-transform:uppercase;letter-spacing:1px;text-align:left'>Agent</th><th style='padding:6px 12px;color:#888;font-size:0.7rem;text-transform:uppercase;letter-spacing:1px;text-align:left'>Status</th></tr></thead><tbody>{rows}</tbody></table></div>"
+
+        agent_panel.markdown(_render_agent_panel(), unsafe_allow_html=True)
+
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        try:
+            report = loop.run_until_complete(run_pipeline(raw_text, filename))
+        finally:
+            loop.close()
+
+        for a in AGENT_NAMES:
+            if st.session_state.agent_statuses[a] == "pending":
+                st.session_state.agent_statuses[a] = "completed"
+                st.session_state.agent_messages[a] = "OK"
+        agent_panel.markdown(_render_agent_panel(), unsafe_allow_html=True)
+
+        progress_bar.progress(1.0)
+
+        if report.summary.total_clauses == 0:
+            logger.error("Pipeline produced 0 clauses — model API may be unreachable or returned errors")
+            failed_agents = [
+                a for a in AGENT_NAMES
+                if st.session_state.agent_statuses.get(a) == "failed"
+            ]
+            if failed_agents:
+                st.session_state.error = (
+                    f"Analysis failed — the {failed_agents[0]} agent could not complete. "
+                    "The model API may be unreachable or returned malformed responses. "
+                    "Check that the vLLM endpoint is running at the configured BASE_URL."
+                )
+            else:
+                st.session_state.error = (
+                    "Analysis could not extract any clauses from the document. "
+                    "The model may be unavailable or the document format may be unsupported. "
+                    "Check your model endpoint configuration."
+                )
+            status_text.markdown("<h3 style='color:#ff4444'>❌ Analysis failed</h3>", unsafe_allow_html=True)
+            st.session_state.report = None
+            st.session_state.analyzing = False
+            progress_bar.empty()
+            status_text.empty()
+            agent_panel.empty()
+            st.rerun()
+            return
+
+        status_text.markdown("<h3 style='color:#55dd55'>✅ Analysis complete!</h3>", unsafe_allow_html=True)
+        st.session_state.report = report
+        st.session_state.error = None
+        st.session_state.copilot_messages = []
+        st.session_state.clause_ai_responses = {}
+        st.session_state.generated_emails = {}
+
+        if not report.processed_normally or report.summary.critical_count == 0 and report.summary.high_count == 0 and report.summary.medium_count == 0:
+            st.session_state.error = (
+                "Analysis completed but no significant risks were detected. "
+                "The model responses may have been incomplete — review the "
+                f"report ({report.summary.total_clauses} clauses analyzed) carefully."
+            )
+
+    except ValueError as e:
+        st.session_state.error = f"Could not process: {e}"
+    except Exception as e:
+        st.session_state.error = "An unexpected error occurred. Try again."
+        logger.error("Analysis error: %s", e)
+    finally:
+        st.session_state.analyzing = False
+        progress_bar.empty()
+        status_text.empty()
+        agent_panel.empty()
+        st.rerun()
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# FALLBACK GENERATORS FOR NEGOTIATION COPILOT
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def _generate_fallback_safer(sc: ScoredClause) -> str:
+    ctype = sc.clause.clause_type.value
+    fallbacks = {
+        "IP_ASSIGNMENT": "Employee assigns only inventions directly related to Company's business, created during working hours using Company resources. Personal projects remain Employee's property.",
+        "ARBITRATION": "Either party may opt out of arbitration within 30 days. Both parties retain the right to bring claims in court.",
+        "NON_COMPETE": "Non-compete limited to 12 months within specific metro areas where Company operates.",
+        "AUTO_RENEWAL": "Agreement renews only with mutual written consent. No automatic renewal.",
+        "TERMINATION": "Either party may terminate with 30 days written notice.",
+        "INDEMNIFICATION": "Indemnification limited to direct damages caused by negligence or willful misconduct.",
+        "LIABILITY_CAP": "Liability capped at the greater of fees paid or $10,000.",
+        "DATA_SHARING": "Data shared only with explicit opt-in consent, revocable at any time.",
+        "GOVERNING_LAW": "Governing law set to user's home state with optional mediation.",
+        "PAYMENT": "Payment due net-30 after invoice receipt. Late fees capped at 5% annually.",
+        "CONFIDENTIALITY": "Confidential information excludes publicly available data and independently developed knowledge.",
+        "NON_SOLICITATION": "Non-solicitation limited to 12 months and applies only to employees directly worked with.",
+        "FORCE_MAJEURE": "Neither party liable for delays due to circumstances beyond reasonable control, with prompt notice.",
+        "SEVERABILITY": "If any provision is found unenforceable, remaining provisions stay in full effect.",
+        "ASSIGNMENT": "Neither party may assign without written consent, not to be unreasonably withheld.",
+        "WAIVER": "Failure to enforce any provision does not constitute waiver. Waivers must be in writing.",
+        "SURVIVAL": "Confidentiality, indemnification, and payment obligations survive termination.",
+        "NOTICE": "Notices effective upon email delivery with read receipt or 3 days after certified mail.",
+    }
+    return fallbacks.get(ctype, "Request a mutual agreement: both parties share rights and obligations equally. Remove one-sided provisions.")
+
+
+def _generate_fallback_message(sc: ScoredClause) -> str:
+    topic = sc.clause.section_heading or sc.clause.clause_type.value.replace("_", " ").title()
+    safer = sc.finding.safer_clause_version or _generate_fallback_safer(sc)
+    return (
+        f"Hi,\n\nI've reviewed the contract and would like to discuss the {topic} clause. "
+        f"I'd suggest the following adjustment:\n\n'{safer}'\n\n"
+        f"This ensures both parties are treated fairly. Would you be open to this change?\n\nThanks!"
+    )
+
+
+def _build_safer_contract(report: FinalReport) -> str:
+    lines: list[str] = []
+    lines.append(f"# SAFER VERSION — {report.contract_name}")
+    lines.append(f"# Auto-generated by ClauseGuard — replaces {report.summary.critical_count + report.summary.high_count} high-risk clauses")
+    lines.append(f"# Original risk score: {report.summary.overall_score}/10")
+    lines.append(f"# Generated: {datetime.now().strftime('%B %d, %Y at %H:%M')}")
+    lines.append("")
+
+    replaced_count = 0
+    for i, sc in enumerate(report.scored_clauses, 1):
+        safer = sc.finding.safer_clause_version
+        sev = sc.finding.severity
+
+        if safer and sev in (Severity.CRITICAL, Severity.HIGH):
+            replaced_count += 1
+            lines.append(f"# {'─' * 70}")
+            lines.append(f"# CLAUSE {i}: REPLACED — {sev.value} Risk — {sc.finding.risk_title}")
+            lines.append(f"# {'─' * 70}")
+            lines.append(f"# ORIGINAL (RISKY):")
+            for orig_line in sc.clause.raw_text.split("\n"):
+                lines.append(f"#   {orig_line.strip()}")
+            lines.append(f"#")
+            lines.append(f"# SAFER VERSION:")
+            lines.append(f"{i}. {sc.clause.section_heading or 'CLAUSE ' + str(i)}")
+            lines.append(f"   {safer}")
+            lines.append("")
+        else:
+            heading = sc.clause.section_heading or f"CLAUSE {i}"
+            lines.append(f"{i}. {heading}")
+            lines.append(f"   {sc.clause.raw_text.strip()}")
+            lines.append("")
+
+    lines.append(f"# {'=' * 70}")
+    lines.append(f"# END OF SAFER CONTRACT")
+    lines.append(f"# {replaced_count} clauses replaced | {report.summary.total_clauses - replaced_count} left unchanged")
+    return "\n".join(lines)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# UI HELPER FUNCTIONS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def seats(n: int) -> str:
+    if n <= 0:
+        return "No parties"
+    if n == 1:
+        return "1 party"
+    return f"{n} parties"
+
+
+def _render_info_card(title: str, body: str, icon: str = "ℹ️", bg: str = "rgba(30,144,255,0.08)", border: str = "#1e90ff") -> str:
+    return f"""<div style="background:{bg};border-left:4px solid {border};border-radius:4px 12px 12px 4px;padding:0.75rem 1rem;margin:0.4rem 0">
+        <span style="font-size:0.85rem;font-weight:600;color:#ccc">{icon} {title}</span>
+        <div style="font-size:0.82rem;color:#aaa;margin-top:0.25rem;line-height:1.5">{body}</div>
+    </div>"""
+
+
+def _render_info_card_raw(html: str) -> None:
+    st.markdown(html, unsafe_allow_html=True)
+
+
+def _switch_to_chat_with_prompt(prompt_text: str) -> None:
+    st.session_state.active_tab = 3
+    st.session_state.pending_ai_query = prompt_text
+    st.rerun()
+
+
+def _render_single_clause_card(sc: ScoredClause, style: dict, show_actions: bool = True) -> None:
+    s = style
+    c = sc.clause
+    f = sc.finding
+
+    st.markdown(f"""
+    <div style="
+        background: linear-gradient(135deg, {s['bg']} 0%, rgba(20,22,30,0.6) 100%);
+        border: 1px solid {s['border']}22;
+        border-left: 4px solid {s['border']};
+        border-radius: 0 12px 12px 0;
+        padding: 1.25rem 1.25rem 0.75rem 1.25rem;
+        margin-bottom: 0.5rem;
+    ">
+        <div style="display:flex;align-items:center;gap:0.6rem;margin-bottom:0.75rem">
+            <span style="
+                display:inline-flex;align-items:center;gap:4px;
+                background:{s['tag_bg']};
+                color:{s['color']};
+                padding:0.25rem 0.75rem;
+                border-radius:20px;
+                font-size:0.73rem;
+                font-weight:700;
+                letter-spacing:0.4px;
+                text-transform:uppercase;
+                white-space:nowrap;
+            ">{s['badge']}</span>
+            <span style="font-weight:600;color:#e8e8e8;font-size:1rem;line-height:1.3">{f.risk_title}</span>
+        </div>
+        <div style="display:flex;gap:1rem;margin-bottom:0.6rem">
+            <span style="color:#888;font-size:0.75rem">📂 {c.section_heading or ''}</span>
+            <span style="color:#888;font-size:0.75rem">🏷️ {c.clause_type.value}</span>
+            <span style="color:#666;font-size:0.75rem">Clause #{c.id}</span>
+        </div>
+    </div>""", unsafe_allow_html=True)
+
+    with st.expander("📜 View Original Text"):
+        st.markdown(f"<div style='background:#1c1d2a;padding:0.85rem;border-radius:8px;font-family:Consolas,monospace;font-size:0.88rem;line-height:1.65;color:#d0d0d0;white-space:pre-wrap'>{c.raw_text}</div>", unsafe_allow_html=True)
+
+    if c.plain_english:
+        st.markdown(f"""<div style="display:flex;gap:0.5rem;align-items:flex-start;margin:0.5rem 0;padding:0.6rem 0.85rem;background:rgba(30,144,255,0.07);border-radius:8px;border:1px solid rgba(30,144,255,0.12)">
+            <span style="font-size:0.95rem;flex-shrink:0">💬</span>
+            <span style="color:#c0cfe0;font-size:0.9rem;line-height:1.5">{c.plain_english}</span>
+        </div>""", unsafe_allow_html=True)
+
+    st.markdown(f"""<div style="display:flex;gap:0.5rem;align-items:flex-start;margin:0.5rem 0;padding:0.6rem 0.85rem;background:{s['bg']};border-radius:8px;border:1px solid {s['border']}18">
+        <span style="font-size:0.95rem;flex-shrink:0">⚠️</span>
+        <div>
+            <div style="color:{s['color']};font-size:0.8rem;font-weight:600;text-transform:uppercase;letter-spacing:0.5px;margin-bottom:0.2rem">Risk</div>
+            <div style="color:#d0d0d0;font-size:0.9rem;line-height:1.55">{f.risk_reason}</div>
+        </div>
+    </div>""", unsafe_allow_html=True)
+
+    if f.recommended_action:
+        st.markdown(f"""<div style="display:flex;gap:0.5rem;align-items:flex-start;margin:0.5rem 0;padding:0.6rem 0.85rem;background:rgba(50,205,50,0.06);border-radius:8px;border:1px solid rgba(50,205,50,0.12)">
+            <span style="font-size:0.95rem;flex-shrink:0">✅</span>
+            <span style="color:#b0d0b0;font-size:0.9rem;line-height:1.5">{f.recommended_action}</span>
+        </div>""", unsafe_allow_html=True)
+
+    if f.impact_scenarios:
+        with st.expander("⚠️ What Could Happen If You Sign This"):
+            for impact in f.impact_scenarios:
+                st.markdown(f"<div style='background:rgba(255,68,68,0.06);padding:0.4rem 0.75rem;margin:0.15rem 0;border-radius:6px;border-left:3px solid {s['border']};font-size:0.85rem;color:#e0a0a0'>• {impact}</div>", unsafe_allow_html=True)
+
+    if show_actions and f.severity not in (Severity.LOW, Severity.INFO):
+        if st.button("✏️ Ask AI to Explain", key=f"explain_{c.id}", use_container_width=True):
+            _switch_to_chat_with_prompt(f"Explain clause {c.id} ({f.risk_title}) in simple terms. What does this mean for me?")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# HEADER
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def render_header() -> None:
+    hero_l, hero_r = st.columns([3, 1])
+    with hero_l:
+        st.markdown("""<div style="background:linear-gradient(135deg,#1e3a5f 0%,#2a5298 100%);padding:1.5rem 2rem;border-radius:16px;margin-bottom:0.5rem">
+            <h1 style="margin:0;color:#fff;font-size:2.2rem">🛡️ ClauseGuard</h1>
+            <p style="margin:0.25rem 0 0 0;color:#c8d8f0;font-size:1.1rem">AI-Powered Contract Clause Risk Analyzer</p>
+        </div>""", unsafe_allow_html=True)
+    with hero_r:
+        st.markdown("<br>", unsafe_allow_html=True)
+        dc1, dc2 = st.columns(2)
+        with dc1:
+            if st.button("⚡ Instant Demo", use_container_width=True, help="See a pre-analyzed NDA report instantly"):
+                _load_demo_report()
+        with dc2:
+            if st.button("🎬 Guided Tour", use_container_width=True, help="Walk through a demo with highlights"):
+                _load_guided_demo()
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# GUIDED DEMO TOUR
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def _render_guided_tour() -> None:
+    if not st.session_state.get("guided_demo"):
+        return
+    step = st.session_state.get("demo_step", 0)
+    tour_steps = [
+        {
+            "title": "🎯 Welcome to ClauseGuard!",
+            "body": "Let's walk through a sample NDA contract analysis. You'll see how 5 AI agents work together to identify risks, explain legal jargon, and help you negotiate better terms. Each agent has a specific role in the pipeline.",
+            "tab": 0,
+            "icon": "🎯",
+        },
+        {
+            "title": "📊 Step 1: Risk Overview Dashboard",
+            "body": "The **Overview tab** shows your contract's risk score, severity breakdown, and the top 3 actions you should take before signing. Check the bar chart to see how many clauses fall into each risk category. The risk score is calculated from 0 (safe) to 10 (extremely risky).",
+            "tab": 0,
+            "icon": "📊",
+        },
+        {
+            "title": "📋 Step 2: Clause-by-Clause Deep Dive",
+            "body": "Switch to the **Clauses tab** to drill into each clause. Critical and High-risk clauses are expanded by default so you see the most dangerous issues first. Each clause card shows: original legal text, plain English translation, the specific risk reason, and a recommended action.",
+            "tab": 1,
+            "icon": "📋",
+        },
+        {
+            "title": "💬 Step 3: Negotiation Copilot",
+            "body": "In the **Negotiation tab**, you'll find side-by-side comparisons: what you signed vs. what you should ask for instead. Each risky clause comes with a pre-written negotiation message and a safer alternative. You can also download a fully rewritten 'Safer Contract' with all high-risk clauses replaced.",
+            "tab": 2,
+            "icon": "💬",
+        },
+        {
+            "title": "🤖 Step 4: AI Chat Assistant",
+            "body": "The **Chat Assistant tab** lets you ask follow-up questions in plain English. The AI has full context of your entire contract and all clause analyses. Try questions like 'Summarize this contract' or 'What's the most dangerous clause and why?' Use the quick-action chips for common questions.",
+            "tab": 3,
+            "icon": "🤖",
+        },
+        {
+            "title": "✅ You're Ready!",
+            "body": "Now you know your way around ClauseGuard. Use the **Instant Demo** button anytime to revisit this tour, or upload your own contract to run a real analysis with the full 5-agent AI pipeline. Remember: always consult a qualified attorney for final legal review.",
+            "tab": 0,
+            "icon": "✅",
+        },
+    ]
+
+    if step < len(tour_steps):
+        ts = tour_steps[step]
+        progress_pct = (step + 1) / len(tour_steps)
+        with st.container():
+            st.markdown(f"""<div style="background:linear-gradient(135deg,#1e3a5f 0%,#2a5298 100%);padding:1.25rem 1.5rem;border-radius:14px;margin:0.5rem 0;border:1px solid rgba(255,255,255,0.1)">
+                <div style="display:flex;align-items:center;gap:0.5rem;margin-bottom:0.25rem">
+                    <span style="font-size:1.5rem">{ts['icon']}</span>
+                    <h3 style="margin:0;color:#fff;font-size:1.2rem">{ts['title']}</h3>
+                </div>
+                <p style="color:#c8d8f0;margin:0.5rem 0;line-height:1.6">{ts['body']}</p>
+                <div style="background:rgba(255,255,255,0.1);border-radius:4px;height:4px;margin-top:0.75rem">
+                    <div style="background:linear-gradient(90deg,#667eea,#764ba2);border-radius:4px;height:100%;width:{progress_pct*100:.0f}%"></div>
+                </div>
+                <div style="text-align:right;font-size:0.75rem;color:rgba(255,255,255,0.5);margin-top:0.25rem">Step {step + 1} of {len(tour_steps)}</div>
+            </div>""", unsafe_allow_html=True)
+
+            c1, c2, c3 = st.columns([1, 1, 1])
+            with c1:
+                if step > 0:
+                    if st.button("⬅️ Previous", key=f"tour_prev_{step}", use_container_width=True):
+                        st.session_state.demo_step = step - 1
+                        st.rerun()
+            with c3:
+                if st.button("Next ➡️" if step < len(tour_steps) - 1 else "✅ Finish Tour", key=f"tour_next_{step}", use_container_width=True):
+                    if step < len(tour_steps) - 1:
+                        st.session_state.demo_step = step + 1
+                        tab_idx = tour_steps[step + 1]["tab"]
+                        st.session_state.active_tab = tab_idx
+                    else:
+                        st.session_state.guided_demo = False
+                    st.rerun()
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# RISK BANNER
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def render_risk_banner() -> None:
+    if not st.session_state.report:
+        return
+    r = st.session_state.report
+    s = r.summary
+    total_risky = s.critical_count + s.high_count
+
+    if total_risky >= 3:
+        st.error(f"🚨 **HIGH ALERT — {total_risky} critical or high-risk clauses detected!** Review carefully before signing. We strongly recommend negotiating these terms.")
+    elif total_risky > 0:
+        st.warning(f"⚠️ **This contract has {total_risky} high-risk clause(s)** — review carefully before signing")
+    elif s.medium_count > 0:
+        st.info(f"ℹ️ **{s.medium_count} medium-risk clause(s) found** — this contract may need attention before signing")
+    else:
+        st.success("✅ **This contract looks clean** — no high or critical risk clauses detected. Still review all terms before signing.")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# ISSUES SUMMARY (displays before tabs)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def render_issues_summary() -> None:
+    report = st.session_state.report
+    criticals = [sc for sc in report.scored_clauses if sc.finding.severity == Severity.CRITICAL]
+    highs = [sc for sc in report.scored_clauses if sc.finding.severity == Severity.HIGH]
+    mediums = [sc for sc in report.scored_clauses if sc.finding.severity == Severity.MEDIUM]
+    all_issues = criticals + highs + mediums
+
+    if not all_issues:
+        if not report.processed_normally:
+            st.warning(
+                "⚠️ **Analysis was incomplete** — the AI risk scorer could not evaluate these clauses. "
+                "All clauses are marked as MEDIUM 'Needs Human Review'. "
+                "This typically means the model API is having issues. Check your vLLM endpoint configuration."
+            )
+            return
+        st.success("✅ No issues found — all clauses look reasonable. Use the tabs below to explore the full analysis.")
+        return
+
+    st.markdown("## 🔍 Issues Found")
+    total_labels = []
+    if criticals:
+        total_labels.append(f"{len(criticals)} critical")
+    if highs:
+        total_labels.append(f"{len(highs)} high")
+    if mediums:
+        total_labels.append(f"{len(mediums)} medium")
+    st.caption(f"{len(all_issues)} clauses need attention — {', '.join(total_labels)}")
+
+    issue_cols = st.columns(min(len(all_issues), 3))
+    for idx, sc in enumerate(all_issues):
+        col_idx = idx % 3
+        style = SEVERITY_STYLE.get(sc.finding.severity, SEVERITY_STYLE[Severity.INFO])
+        with issue_cols[col_idx]:
+            reason_preview = sc.finding.risk_reason[:120]
+            if len(sc.finding.risk_reason) > 120:
+                reason_preview += "..."
+            st.markdown(
+                f"""<div style="background:#1e1e2e;border-radius:12px;padding:1rem;margin:0.3rem 0;
+                    border-top:3px solid {style['border']};border-left:1px solid #333;border-right:1px solid #333;border-bottom:1px solid #333">
+                    <div style="font-weight:700;margin-bottom:0.3rem;font-size:0.8rem">{style['badge']}</div>
+                    <div style="font-size:0.9rem;color:#e0e0e0;line-height:1.4;margin-bottom:0.5rem"><b>{sc.finding.risk_title}</b></div>
+                    <div style="font-size:0.8rem;color:#aaa;line-height:1.4">{reason_preview}</div>
+                </div>""",
+                unsafe_allow_html=True,
+            )
+    st.markdown("")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# TAB 1: OVERVIEW
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def render_overview_tab() -> None:
+    report = st.session_state.report
+    s = report.summary
+
+    st.markdown("### 📊 Risk Score Dashboard")
+    st.caption(f"Contract Type: **{s.contract_type}** • {s.total_clauses} clauses analyzed • {s.critical_count + s.high_count + s.medium_count} need attention")
+
+    col_a, col_b, col_c = st.columns([1, 2, 1])
+    with col_a:
+        score = s.overall_score
+        if score >= 7:
+            sc_color = "#ff4444"
+            label = "High Risk"
+            bg_glow = "rgba(255,68,68,0.08)"
+        elif score >= 4:
+            sc_color = "#ff8c00"
+            label = "Medium Risk"
+            bg_glow = "rgba(255,140,0,0.06)"
+        else:
+            sc_color = "#32cd32"
+            label = "Low Risk"
+            bg_glow = "rgba(50,205,50,0.06)"
+        st.markdown(f"""<div style="background:#1e1e2e;border-radius:16px;padding:1.5rem;text-align:center;border:1px solid #333;box-shadow:0 0 30px {bg_glow}">
+            <div style="font-size:0.8rem;color:#888;text-transform:uppercase;letter-spacing:2px">Risk Score</div>
+            <div style="font-size:3.5rem;font-weight:900;color:{sc_color};line-height:1.1">{score}<span style="font-size:1.5rem;color:#666">/10</span></div>
+            <div style="font-size:0.85rem;color:{sc_color};margin-top:0.2rem;font-weight:600">{label}</div>
+            <div style="font-size:0.82rem;color:#aaa;margin-top:0.5rem">{s.critical_count}C · {s.high_count}H · {s.medium_count}M · {s.low_count}L</div>
+        </div>""", unsafe_allow_html=True)
+    with col_b:
+        max_val = max(s.critical_count, s.high_count, s.medium_count, s.low_count,
+                      s.total_clauses - s.critical_count - s.high_count - s.medium_count - s.low_count, 1)
+        chart_data = pd.DataFrame({
+            "Severity": ["Critical", "High", "Medium", "Low", "Info"],
+            "Count": [s.critical_count, s.high_count, s.medium_count, s.low_count,
+                      max(s.total_clauses - s.critical_count - s.high_count - s.medium_count - s.low_count, 0)],
+        })
+        st.bar_chart(chart_data.set_index("Severity"), use_container_width=True, height=220)
+    with col_c:
+        risky = s.critical_count + s.high_count + s.medium_count
+        pct = (risky / s.total_clauses * 100) if s.total_clauses > 0 else 0
+        if pct >= 50:
+            attn_color = "#ff4444"
+            attn_label = "Review Urgently"
+        elif pct >= 25:
+            attn_color = "#ff8c00"
+            attn_label = "Needs Review"
+        else:
+            attn_color = "#32cd32"
+            attn_label = "Mostly Clean"
+        st.markdown(f"""<div style="background:#1e1e2e;border-radius:12px;padding:1.25rem;text-align:center;border:1px solid #333;height:100%">
+            <div style="font-size:0.75rem;color:#888;text-transform:uppercase;letter-spacing:1px">Needs Attention</div>
+            <div style="font-size:2.5rem;font-weight:900;color:{attn_color}">{risky}<span style="font-size:1rem;color:#666">/{s.total_clauses}</span></div>
+            <div style="font-size:0.85rem;color:{attn_color};font-weight:500">{attn_label}</div>
+            <div style="font-size:0.8rem;color:#888;margin-top:0.25rem">{pct:.0f}% of clauses</div>
+        </div>""", unsafe_allow_html=True)
+
+    st.markdown("")
+    st.markdown("### ⚡ Top 3 Actions Before Signing")
+    if report.top_3_actions:
+        for i, action in enumerate(report.top_3_actions, 1):
+            colors = ["#ff4444", "#ff8c00", "#ffd700"]
+            emojis = ["①", "②", "③"]
+            st.markdown(f"""<div style="background:#1e1e2e;border-radius:10px;padding:1rem 1.25rem;margin:0.4rem 0;
+                border-left:4px solid {colors[i-1]}">
+                <b style="color:#8ab4f8;font-size:1.1rem">{emojis[i-1]}</b>
+                <span style="margin-left:0.5rem;color:#e8e8e8">{action}</span></div>""", unsafe_allow_html=True)
+    else:
+        st.info("No specific actions needed — this contract appears well-balanced.")
+
+    criticals = [sc for sc in report.scored_clauses if sc.finding.severity == Severity.CRITICAL]
+    if criticals:
+        st.markdown("")
+        st.markdown("### ⚠️ What Could Happen If You Sign This?")
+        st.caption("Realistic AI-generated consequence scenarios based on these clause patterns. These are illustrative examples — consult an attorney for legal advice.")
+        for idx, sc in enumerate(criticals[:3]):
+            scenarios = sc.finding.impact_scenarios
+            if not scenarios:
+                scenarios = ["You may face significant legal or financial consequences from this clause."]
+            st.markdown(f"**{idx + 1}. 🔴 {sc.finding.risk_title}**")
+            for scenario in scenarios:
+                st.markdown(f"<div style='background:rgba(255,68,68,0.08);border-left:3px solid #ff4444;padding:0.5rem 0.75rem;margin:0.2rem 0;margin-left:1rem;border-radius:4px;font-size:0.9rem;color:#e0a0a0'>{scenario}</div>", unsafe_allow_html=True)
+
+    high_risks = [sc for sc in report.scored_clauses if sc.finding.severity == Severity.HIGH]
+    if high_risks:
+        st.markdown("")
+        st.markdown("### 🟠 High-Risk Clauses at a Glance")
+        for sc in high_risks:
+            style = SEVERITY_STYLE[Severity.HIGH]
+            reason_preview = sc.finding.risk_reason[:120]
+            if len(sc.finding.risk_reason) > 120:
+                reason_preview += "..."
+            st.markdown(f"""<div style="background:{style['bg']};border-left:3px solid {style['border']};padding:0.6rem 0.9rem;margin:0.3rem 0;border-radius:4px">
+                <b style="color:{style['color']}">{sc.finding.risk_title}</b>
+                <span style="color:#aaa;font-size:0.85rem;margin-left:0.5rem">— {reason_preview}</span>
+            </div>""", unsafe_allow_html=True)
+
+    medium_risks = [sc for sc in report.scored_clauses if sc.finding.severity == Severity.MEDIUM]
+    if medium_risks:
+        st.markdown("")
+        st.markdown("### 🟡 Medium-Risk Clauses")
+        for sc in medium_risks:
+            style = SEVERITY_STYLE[Severity.MEDIUM]
+            reason_preview = sc.finding.risk_reason[:80]
+            if len(sc.finding.risk_reason) > 80:
+                reason_preview += "..."
+            st.markdown(f"""<div style="background:{style['bg']};border-left:3px solid {style['border']};padding:0.5rem 0.8rem;margin:0.2rem 0;border-radius:4px;font-size:0.9rem">
+                <b style="color:{style['color']}">{sc.finding.risk_title}</b>
+                <span style="color:#999;margin-left:0.3rem">— {reason_preview}</span>
+            </div>""", unsafe_allow_html=True)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# TAB 2: CLAUSES
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def render_clauses_tab() -> None:
+    report = st.session_state.report
+    st.markdown("### 📋 Clause-by-Clause Analysis")
+    st.caption("Each issue below shows the original legal text, plain-English translation, risk assessment, and recommended actions.")
+
+    filter_cols = st.columns(5)
+    show_crit = filter_cols[0].checkbox("🔴 Critical", value=True)
+    show_high = filter_cols[1].checkbox("🟠 High", value=True)
+    show_med  = filter_cols[2].checkbox("🟡 Medium", value=True)
+    show_low  = filter_cols[3].checkbox("🟢 Low", value=False)
+    show_info = filter_cols[4].checkbox("ℹ️ Info", value=False)
+
+    visible = {Severity.CRITICAL: show_crit, Severity.HIGH: show_high,
+               Severity.MEDIUM: show_med, Severity.LOW: show_low, Severity.INFO: show_info}
+
+    default_s = SEVERITY_STYLE[Severity.INFO]
+    issue_num = 0
+    for sc in report.scored_clauses:
+        sev = sc.finding.severity
+        if not visible.get(sev, False):
+            continue
+        issue_num += 1
+        style = SEVERITY_STYLE.get(sev, default_s)
+
+        st.markdown(f"""
+        <div style="display:flex;align-items:center;gap:0.75rem;margin:1.5rem 0 0.75rem 0">
+            <span style="
+                background:{style['border']};
+                color:#fff;
+                min-width:2rem;height:2rem;
+                border-radius:50%;
+                display:inline-flex;align-items:center;justify-content:center;
+                font-weight:800;font-size:0.9rem;
+            ">#{issue_num}</span>
+            <div style="background:linear-gradient(90deg, {style['border']}44 0%, transparent 100%);height:1px;flex:1"></div>
+        </div>""", unsafe_allow_html=True)
+
+        _render_single_clause_card(sc, style, show_actions=True)
+
+    if issue_num == 0:
+        st.info("Select severity levels above to view issues. Try enabling Critical and High to see the most important clauses that need your attention.")
+    else:
+        st.caption(f"Showing {issue_num} of {report.summary.total_clauses} clauses — use severity filters above to adjust view")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# TAB 3: NEGOTIATION
+# ═════════════════════════════════════════════════════��═════════════════════════
+
+def _highlight_diff(original: str, safer: str) -> tuple[str, str]:
+    original_span = f"<span style='background:rgba(255,68,68,0.20);padding:0 2px;border-radius:2px;text-decoration:line-through'>{original}</span>"
+    safer_span = f"<span style='background:rgba(50,205,50,0.20);padding:0 2px;border-radius:2px;font-weight:600'>{safer}</span>"
+    return original_span, safer_span
+
+
+def generate_negotiation_email(sc: ScoredClause, recipient: str = "[Other Party]") -> str:
+    topic = sc.clause.section_heading or sc.clause.clause_type.value.replace("_", " ").title()
+    safer = sc.finding.safer_clause_version or _generate_fallback_safer(sc)
+    risk_reason = sc.finding.risk_reason
+    return (
+        f"Subject: Proposed adjustment — {topic} clause\n\n"
+        f"Hi {recipient},\n\n"
+        f"I've reviewed the contract and have a concern about the {topic} clause.\n\n"
+        f"My concern: {risk_reason}\n\n"
+        f"I'd suggest the following alternative language to make this fair for both parties:\n\n"
+        f'"{safer}"\n\n'
+        f"Let me know your thoughts — I'm happy to discuss further.\n\n"
+        f"Best regards"
+    )
+
+
+def _render_email_card(sc: ScoredClause, recipient: str = "[Other Party]") -> None:
+    recipient_input = st.text_input("Recipient name", value=recipient, key=f"recipient_{sc.clause.id}")
+    email_body = generate_negotiation_email(sc, recipient_input)
+    st.markdown("**📧 Formal Email Draft**")
+    st.code(email_body, language=None)
+    col_copy, col_info = st.columns([1, 3])
+    with col_copy:
+        if st.button("📋 Copy to Clipboard", key=f"copy_email_{sc.clause.id}"):
+            st.toast("Email copied!", icon="📋")
+    with col_info:
+        st.caption("Click the code block above to select all text, then Ctrl+C to copy")
+
+
+def render_negotiation_tab() -> None:
+    report = st.session_state.report
+    default_s = SEVERITY_STYLE[Severity.INFO]
+
+    st.markdown("### 💬 Negotiation Copilot")
+    st.caption("Each risky clause shows what you signed vs. a safer alternative, side-by-side. Use the pre-written messages or generate a formal email to send to the other party.")
+
+    negotiable = [sc for sc in report.scored_clauses if sc.finding.severity not in (Severity.LOW, Severity.INFO)]
+    if not negotiable:
+        st.success("✅ No actionable risks detected — this contract looks reasonable!")
+    else:
+        st.info(f"📋 **{len(negotiable)} clauses** flagged for negotiation below")
+
+        for i, sc in enumerate(negotiable):
+            style = SEVERITY_STYLE.get(sc.finding.severity, default_s)
+            sev_label = sc.finding.severity.value
+
+            st.markdown(f"""<div style="background:{style['bg']};border-left:4px solid {style['border']};padding:0.6rem 1rem;border-radius:4px 10px 10px 4px;margin:1.2rem 0 0.5rem 0">
+                <span style="font-weight:700;color:{style['color']}">{style['badge']}</span>
+                <span style="font-weight:600;color:#e0e0e0;margin-left:0.5rem">{sc.finding.risk_title}</span>
+                <span style="color:#888;font-size:0.8rem;margin-left:0.8rem">Clause {sc.clause.id}</span>
+            </div>""", unsafe_allow_html=True)
+
+            st.markdown("**📋 Why This Matters**")
+            st.markdown(f"<div style='color:#ccc;font-size:0.9rem;line-height:1.55;margin-bottom:0.75rem;padding:0.5rem 0.75rem;background:rgba(255,255,255,0.02);border-radius:8px'>{sc.finding.risk_reason}</div>", unsafe_allow_html=True)
+
+            neg_l, neg_r = st.columns(2)
+            with neg_l:
+                st.markdown("**⚠️ Current Clause (Risky)**")
+                text_to_show = sc.clause.raw_text[:500]
+                if len(sc.clause.raw_text) > 500:
+                    text_to_show += "..."
+                st.markdown(f"<div style='background:rgba(255,68,68,0.08);padding:0.75rem;border-radius:8px;border:1px solid rgba(255,68,68,0.2);font-size:0.85rem;line-height:1.6;color:#e0e0e0'>{text_to_show}</div>", unsafe_allow_html=True)
+
+            with neg_r:
+                st.markdown("**💡 Safer Alternative**")
+                safer = sc.finding.safer_clause_version
+                if not safer:
+                    safer = _generate_fallback_safer(sc)
+                st.markdown(f"<div style='background:rgba(50,205,50,0.08);padding:0.75rem;border-radius:8px;border:1px solid rgba(50,205,50,0.2);font-size:0.85rem;line-height:1.6;color:#e0e0e0'>{safer}</div>", unsafe_allow_html=True)
+
+            if sc.finding.recommended_action:
+                st.markdown(f"**✅ Recommended:** {sc.finding.recommended_action}")
+
+            neg_msg = sc.finding.negotiation_message
+            if not neg_msg:
+                neg_msg = _generate_fallback_message(sc)
+            st.markdown("**📧 Quick Negotiation Message**")
+            st.code(neg_msg, language=None)
+
+            if sc.finding.impact_scenarios:
+                st.markdown("**⚠️ Consequences of Not Negotiating**")
+                for impact in sc.finding.impact_scenarios:
+                    st.markdown(f"<div style='background:rgba(255,68,68,0.06);padding:0.35rem 0.75rem;margin:0.15rem 0;margin-left:0.5rem;border-radius:4px;font-size:0.85rem;color:#ff9999'>• {impact}</div>", unsafe_allow_html=True)
+
+            with st.expander("📧 Generate Formal Email to Send"):
+                _render_email_card(sc)
+
+            if i < len(negotiable) - 1:
+                st.divider()
+
+    safe_contract = _build_safer_contract(report)
+    with st.expander("📋 Preview Safer Contract"):
+        preview_max = 3500
+        preview_text = safe_contract[:preview_max]
+        if len(safe_contract) > preview_max:
+            preview_text += f"\n\n... (showing first {preview_max} chars of {len(safe_contract)} — download full contract at bottom of page)"
+        st.code(preview_text, language=None)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# TAB 4: CHAT ASSISTANT
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def render_chat_tab() -> None:
+    report = st.session_state.report
+    st.markdown("### 🤖 Chat Assistant")
+    st.caption("Ask questions about your contract in plain English. The AI has full context of every clause, risk assessment, and recommended action — all injected into this conversation automatically.")
+
+    cache_key = id(report)
+    if st.session_state.get("copilot_cache_key") != cache_key:
+        raw_text = st.session_state.get("copilot_raw_text", "")
+        st.session_state.copilot_context = build_contract_context(raw_text, report)
+        st.session_state.copilot_cache_key = cache_key
+
+    copilot_context = st.session_state.copilot_context
+
+    if not st.session_state.copilot_messages:
+        total_risky = report.summary.critical_count + report.summary.high_count
+        if total_risky > 0:
+            welcome = (
+                f"I've analyzed your contract and found **{total_risky} high-risk clause(s)** "
+                f"(risk score: **{report.summary.overall_score}/10**). "
+                "You can ask me to:\n\n"
+                "- Explain any clause in simple terms\n"
+                "- Tell you which clauses are risky and why\n"
+                "- Suggest safer wording for specific clauses\n"
+                "- Help you draft a negotiation message\n"
+                "- Describe what could happen if you sign as-is\n"
+                "- Compare clauses to industry standards\n\n"
+                "What would you like to know?"
+            )
+        else:
+            welcome = (
+                f"I've analyzed your contract and it looks reasonable (risk score: **{report.summary.overall_score}/10**). "
+                "You can ask me to explain any clause, check for potential hidden issues, or compare terms to standard practices. "
+                "What would you like to know?"
+            )
+        with st.chat_message("assistant"):
+            st.markdown(welcome)
+        st.session_state.copilot_messages = [{"role": "assistant", "content": welcome}]
+
+    st.markdown("**💡 Click a question to ask instantly:**")
+    chip_cols = st.columns(4)
+    quick_prompts = [
+        "Summarize this contract in 3 sentences",
+        "What's the most dangerous clause and why?",
+        "Suggest safer wording for the IP clause",
+        "What should I negotiate first?",
+        "Explain the non-compete in simple English",
+        "Are there any hidden fees, penalties, or traps?",
+        "What happens if I breach this contract?",
+        "Draft an email requesting changes to all risky clauses",
+    ]
+    for idx, prompt in enumerate(quick_prompts):
+        col = chip_cols[idx % 4]
+        with col:
+            if st.button(prompt, key=f"chip_{idx}", use_container_width=True):
+                st.session_state.pending_ai_query = prompt
+                st.rerun()
+
+    for msg in st.session_state.copilot_messages:
+        with st.chat_message(msg["role"]):
+            st.markdown(msg["content"])
+
+    if st.session_state.get("pending_ai_query"):
+        query = st.session_state.pending_ai_query
+        st.session_state.pending_ai_query = None
+        if copilot_context:
+            st.session_state.copilot_messages.append({"role": "user", "content": query})
+            with st.chat_message("user"):
+                st.markdown(query)
+            with st.chat_message("assistant"):
+                with st.spinner("Thinking — analyzing contract context..."):
+                    chat_history = st.session_state.copilot_messages[:-1]
+                    response = run_copilot_sync(copilot_context, chat_history, query)
+                    st.markdown(response)
+                st.session_state.copilot_messages.append({"role": "assistant", "content": response})
+            st.rerun()
+
+    if prompt := st.chat_input("Ask about this contract...", key="copilot_chat_input"):
+        if not copilot_context:
+            st.warning("No contract analysis available. Please upload and analyze a contract first.")
+        else:
+            st.session_state.copilot_messages.append({"role": "user", "content": prompt})
+            with st.chat_message("user"):
+                st.markdown(prompt)
+            with st.chat_message("assistant"):
+                with st.spinner("Thinking — analyzing contract context..."):
+                    chat_history = st.session_state.copilot_messages[:-1]
+                    response = run_copilot_sync(copilot_context, chat_history, prompt)
+                    st.markdown(response)
+                st.session_state.copilot_messages.append({"role": "assistant", "content": response})
+
+    if st.session_state.copilot_messages:
+        cc1, cc2, cc3 = st.columns([1, 2, 1])
+        with cc1:
+            if st.button("🗑️ Clear Chat", key="copilot_clear", use_container_width=True):
+                st.session_state.copilot_messages = []
+                st.rerun()
+        with cc3:
+            st.caption(f"{len(st.session_state.copilot_messages)} messages")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# SIDEBAR
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def render_sidebar() -> None:
+    with st.sidebar:
+        st.markdown("""<div style="background:#1e2a3a;border-radius:12px;padding:1.25rem;border:1px solid #3a4a5a">
+            <h4 style="margin:0 0 0.5rem 0;color:#fff">🎯 How It Works</h4>
+            <ol style="margin:0;padding-left:1.25rem;font-size:0.9rem;color:#ccc;line-height:2">
+                <li>Upload any contract file (PDF, DOCX, TXT)</li>
+                <li>5 specialized AI agents analyze every clause</li>
+                <li>Get a detailed risk report with plain English explanations</li>
+                <li>Use Negotiation Copilot to draft counter-proposals</li>
+                <li>Chat with the AI Copilot for any follow-up questions</li>
+            </ol>
+        </div>""", unsafe_allow_html=True)
+
+        st.markdown("")
+        st.markdown("""<div style="background:#1e2a3a;border-radius:12px;padding:1.25rem;border:1px solid #3a4a5a">
+            <h4 style="margin:0 0 0.5rem 0;color:#fff">🤖 5-Agent AI Pipeline</h4>
+            <div style="font-size:0.85rem;color:#ccc;line-height:2">
+                <p style="margin:0.2rem 0"><b style="color:#8ab4f8">① Extractor</b> — Segments contract into individual clauses</p>
+                <p style="margin:0.2rem 0"><b style="color:#8ab4f8">② Classifier</b> — Labels each clause by legal type</p>
+                <p style="margin:0.2rem 0"><b style="color:#8ab4f8">③ Risk Scorer</b> — Evaluates severity of each clause</p>
+                <p style="margin:0.2rem 0"><b style="color:#8ab4f8">④ Translator</b> — Converts legalese to plain English</p>
+                <p style="margin:0.2rem 0"><b style="color:#8ab4f8">⑤ Reporter</b> — Compiles the final risk report</p>
+            </div>
+        </div>""", unsafe_allow_html=True)
+
+        if st.session_state.report:
+            s = st.session_state.report.summary
+            total_risky = s.critical_count + s.high_count
+            st.markdown("")
+            st.markdown("#### 📊 Contract Stats")
+
+            risk_delta = f"{total_risky} high-risk" if total_risky > 0 else "Clean"
+            st.metric(
+                "🎯 Risk Score",
+                f"{s.overall_score}/10",
+                delta=risk_delta,
+                delta_color="inverse" if total_risky > 0 else "normal",
+            )
+            st.metric("📄 Total Clauses", s.total_clauses)
+
+            has_any_risks = False
+            for icon, label, key in [
+                ("🔴", "Critical", "critical_count"),
+                ("🟠", "High", "high_count"),
+                ("🟡", "Medium", "medium_count"),
+                ("🟢", "Low", "low_count"),
+            ]:
+                count = getattr(s, key, 0)
+                if count > 0:
+                    has_any_risks = True
+                    st.metric(f"{icon} {label}", count)
+
+            st.divider()
+            st.markdown(f"**Contract Type:** {s.contract_type}")
+            st.markdown(f"**Analyzed:** {st.session_state.report.generated_at.strftime('%b %d, %Y at %H:%M')}")
+
+            if not st.session_state.report.processed_normally:
+                st.caption("⚠️ Report may not cover all clauses due to processing constraints.")
+
+        st.markdown("")
+        st.markdown("""<div style="background:#1e2a3a;border-radius:12px;padding:1.25rem;border:1px solid #3a4a5a">
+            <h4 style="margin:0 0 0.5rem 0;color:#fff">⚡ Powered by</h4>
+            <p style="font-size:0.85rem;color:#ccc;margin:0;line-height:1.8">
+                Qwen2.5 via vLLM on AMD MI300X<br>
+                OpenAI-compatible API<br>
+                Streamlit • Python 3.10+
+            </p>
+            <div style="margin-top:0.5rem;padding:0.3rem 0.5rem;background:#1a0533;border-radius:6px;border:1px solid #667eea;text-align:center;font-size:0.7rem;color:#aabbcc">
+                🏷️ AMD Developer Cloud
+            </div>
+        </div>""", unsafe_allow_html=True)
+
+        st.markdown("")
+        st.markdown("""<div style="font-size:0.7rem;color:#555;text-align:center;margin-top:1rem">
+            <p style="margin:0">⚠️ Not legal advice. AI-generated analysis.</p>
+            <p style="margin:0">Always consult a qualified attorney before signing.</p>
+        </div>""", unsafe_allow_html=True)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# MAIN APP ENTRY POINT
+# ═══════════════════════════════════════════════════════════════════════════════
+
+st.set_page_config(
+    page_title="ClauseGuard — AI Contract Risk Analyzer",
+    page_icon="🛡️",
+    layout="wide",
+    initial_sidebar_state="expanded",
+)
+st.markdown(CUSTOM_CSS, unsafe_allow_html=True)
+_init_session_state()
+
+render_header()
+
+_render_guided_tour()
+
+render_risk_banner()
+
+uploaded_file = st.file_uploader(
+    "Choose a contract file",
+    type=ALLOWED_EXTENSIONS,
+    help="Supported: PDF, TXT, DOCX • Maximum file size: 10MB",
+    key="file_uploader",
+)
+
+if uploaded_file is not None:
+    fb = uploaded_file.read()
+    st.session_state.uploaded_filename = uploaded_file.name
+    st.session_state.uploaded_bytes = fb
+    if len(fb) > MAX_FILE_SIZE_BYTES:
+        st.error(f"File too large ({len(fb)/1024/1024:.1f}MB). Max file size is {MAX_FILE_SIZE_MB}MB. Please reduce the file size or split the contract.")
+    else:
+        c1, c2 = st.columns([2, 1])
+        with c1:
+            st.success(f"**{uploaded_file.name}** loaded successfully — `{len(fb)/1024:.1f} KB` ready for analysis")
+        with c2:
+            analyze_disabled = st.session_state.analyzing
+            if st.button(
+                "🔍 Analyze Contract",
+                type="primary",
+                disabled=analyze_disabled,
+                use_container_width=True,
+                help="Run the full 5-agent AI pipeline on this contract",
+            ):
+                st.session_state.analyzing = True
+                st.session_state.error = None
+                st.session_state.guided_demo = False
+                st.rerun()
+
+if st.session_state.analyzing and st.session_state.uploaded_bytes:
+    _run_analysis()
+
+if st.session_state.error:
+    st.error(st.session_state.error)
+    if "DEEPSEEK_API_KEY" in st.session_state.error:
+        st.info("💡 To use ClauseGuard, set the `BASE_URL` and `MODEL_NAME` in your `.env` file to point to your Qwen/vLLM endpoint. See the README for setup instructions.")
+
+if st.session_state.report:
+    report = st.session_state.report
+    s = report.summary
+
+    st.divider()
+
+    render_issues_summary()
+
+    active_tab = st.radio(
+        "Navigate between sections",
+        TAB_NAMES,
+        index=min(st.session_state.get("active_tab", 0), len(TAB_NAMES) - 1),
+        label_visibility="collapsed",
+        horizontal=True,
+    )
+    st.session_state.active_tab = TAB_NAMES.index(active_tab)
+    tab_index = st.session_state.active_tab
+
+    if tab_index == 0:
+        render_overview_tab()
+    elif tab_index == 1:
+        render_clauses_tab()
+    elif tab_index == 2:
+        render_negotiation_tab()
+    elif tab_index == 3:
+        render_chat_tab()
+
+    st.divider()
+    st.markdown("### 📥 Download Your Report")
+    st.caption("Download the full analysis in your preferred format to share with legal counsel or reference later.")
+
+    dl_cols = st.columns(3)
+    with dl_cols[0]:
+        st.download_button(
+            "📝 Download Markdown Report",
+            data=report.markdown_report or "# ClauseGuard Report\n\nRun analysis first.",
+            file_name=f"clauseguard_report_{report.contract_name.replace('.','_')}.md",
+            mime="text/markdown",
+            use_container_width=True,
+        )
+    with dl_cols[1]:
+        safe_contract = _build_safer_contract(report)
+        st.download_button(
+            "🛡️ Download Safer Contract",
+            data=safe_contract,
+            file_name=f"safer_{report.contract_name.replace('.txt','').replace('.pdf','').replace('.docx','')}.txt",
+            mime="text/plain",
+            use_container_width=True,
+        )
+    with dl_cols[2]:
+        csv_lines = ["Clause ID,Type,Severity,Risk Title,Risk Reason,Recommended Action,Plain English,Negotiation Message"]
+        for sc in report.scored_clauses:
+            csv_lines.append(
+                f'"{sc.clause.id}","{sc.clause.clause_type.value}","{sc.finding.severity.value}","{sc.finding.risk_title}","{sc.finding.risk_reason}","{sc.finding.recommended_action}","{sc.clause.plain_english or ""}","{sc.finding.negotiation_message or ""}"'
+            )
+        st.download_button(
+            "📊 Download CSV Data",
+            data="\n".join(csv_lines),
+            file_name=f"clauseguard_data_{report.contract_name.replace('.','_')}.csv",
+            mime="text/csv",
+            use_container_width=True,
+        )
+
+    st.caption(
+        f"Generated {report.generated_at.strftime('%B %d, %Y at %H:%M')} "
+        f"• {s.contract_type} • {s.total_clauses} clauses analyzed"
+        f"{' • ⚠️ Partial analysis' if not report.processed_normally else ''}"
+    )
+
+render_sidebar()

config/__init__.py

@@ -0,0 +1,39 @@
+"""ClauseGuard configuration package."""
+
+from clauseguard.config.settings import (
+    API_KEY,
+    BASE_URL,
+    DEEPSEEK_API_KEY,
+    MAX_CLAUSES,
+    MAX_TOKENS,
+    MODEL_NAME,
+    TEMPERATURE,
+    TIMEOUT_SECONDS,
+    validate_config,
+)
+from clauseguard.config.prompts import (
+    CLASSIFIER_SYSTEM_PROMPT,
+    EXTRACTOR_SYSTEM_PROMPT,
+    REPORTER_SYSTEM_PROMPT,
+    RISK_SCORER_SYSTEM_PROMPT,
+    TRANSLATOR_SYSTEM_PROMPT,
+)
+from clauseguard.config.copilot_prompts import COPILOT_SYSTEM_PROMPT
+
+__all__ = [
+    "API_KEY",
+    "BASE_URL",
+    "CLASSIFIER_SYSTEM_PROMPT",
+    "COPILOT_SYSTEM_PROMPT",
+    "DEEPSEEK_API_KEY",
+    "EXTRACTOR_SYSTEM_PROMPT",
+    "MAX_CLAUSES",
+    "MAX_TOKENS",
+    "MODEL_NAME",
+    "REPORTER_SYSTEM_PROMPT",
+    "RISK_SCORER_SYSTEM_PROMPT",
+    "TEMPERATURE",
+    "TIMEOUT_SECONDS",
+    "TRANSLATOR_SYSTEM_PROMPT",
+    "validate_config",
+]

config/copilot_prompts.py

@@ -0,0 +1,62 @@
+"""System prompts for the ClauseGuard Copilot — the interactive AI chat assistant."""
+
+COPILOT_SYSTEM_PROMPT: str = """
+You are ClauseGuard Copilot — an AI legal assistant embedded inside a contract analysis system.
+
+You have access to a fully analyzed contract including: full contract text, clause-by-clause analysis with severity ratings, risk reasons, plain-English explanations, recommended actions, safer wording alternatives, and negotiation messages.
+
+## YOUR ROLE
+
+Act as a practical legal assistant. Help users:
+- UNDERSTAND what each clause means in plain language
+- EVALUATE how risky each clause is — and why
+- FIX risky clauses with specific, realistic rewrites
+- NEGOTIATE better terms with ready-to-send messages
+- ANTICIPATE real-world consequences of signing as-is
+
+Always base your answers on the provided contract context.
+
+## RESPONSE FORMAT
+
+When discussing a specific clause, include ALL of:
+1. **Severity** — (e.g. 🔴 CRITICAL) with a short title
+2. **What this means** — plain-English explanation (2-3 sentences)
+3. **Why this is risky** — specific reason citing the actual clause language
+4. **What could happen** — 2-3 realistic consequences
+5. **How to fix it** — 2-4 specific, practical steps
+6. **Suggested wording** — a rewritten version that is balanced and realistic
+7. **What to say** — a short, professional negotiation message
+
+## TASK TYPES
+
+**"What does this mean?"** → Respond with the full format above (or a shorter version if the clause is simple).
+
+**"Is this safe?"** → Respond with: severity level, why it's risky or not, short conclusion.
+
+**"How do I fix this?"** → Respond with: what's wrong, what to change, improved wording.
+
+**"What should I say?"** → Give a real, copy-paste negotiation message.
+
+**"What happens if I sign?"** → Give 2-3 realistic, practical consequences.
+
+## BEHAVIOR RULES
+
+- ALWAYS use the provided clause data — reference severity levels and risk reasons
+- BE SPECIFIC — tie every answer to the actual contract language
+- BE CLEAR — avoid legal jargon, use simple human language
+- BE ACTIONABLE — when users ask what to do, give concrete steps
+- NEVER hallucinate clauses not in the contract
+- NEVER say "consult a lawyer" as your only advice
+- NEVER answer without using the provided contract context
+
+## REWRITING RULES
+
+When writing "Suggested wording":
+- Do NOT delete the clause entirely
+- Do NOT make it unrealistic or one-sided
+- Keep legal tone and structure
+- Only reduce risk by adding limits, carve-outs, conditions, and mutual obligations
+- The rewrite must be balanced and something a counterparty would actually accept
+
+Your goal: make users confident about what to do next — give them exact steps to improve their contract.
+"""

config/prompts.py

@@ -0,0 +1,140 @@
+"""Prompt templates for all 5 ClauseGuard agents — optimized for Qwen2.5 via vLLM."""
+
+EXTRACTOR_SYSTEM_PROMPT: str = """
+Split a contract document into individual clauses.
+
+Return ONLY a JSON object with this exact structure:
+{
+  "clauses": [
+    {
+      "id": 1,
+      "raw_text": "The full clause text",
+      "plain_english": null,
+      "clause_type": "OTHER",
+      "section_heading": "CONFIDENTIALITY",
+      "position": 1
+    }
+  ],
+  "contract_type": "Other",
+  "total_clauses": 3
+}
+
+Rules:
+- Split on numbered sections (1., 2., Article 1), ALL CAPS headings, or paragraph breaks
+- Each clause must be 5+ words
+- Max 60 clauses
+- Keep raw_text exactly as it appears in the document
+- For plain_english, use null (it will be filled later)
+- For clause_type, use "OTHER" (it will be classified later)
+
+Do NOT include markdown fences, explanations, or any text outside the JSON.
+"""
+
+CLASSIFIER_SYSTEM_PROMPT: str = """
+Classify each contract clause by type.
+
+Clause types: NDA, IP_ASSIGNMENT, NON_COMPETE, ARBITRATION, AUTO_RENEWAL,
+LIABILITY_CAP, TERMINATION, DATA_SHARING, GOVERNING_LAW, PAYMENT,
+INDEMNIFICATION, OTHER
+
+Contract types: NDA, Employment, Freelance, SaaS, Other
+
+You will receive a JSON object with an array of clauses. For each clause, fill in
+only the "clause_type" field. Also set "contract_type" at the top level.
+
+Do NOT change raw_text, id, position, or section_heading.
+
+Return ONLY the updated JSON object. No markdown fences.
+"""
+
+RISK_SCORER_SYSTEM_PROMPT: str = """
+Evaluate the risk severity of each contract clause. You will receive a JSON object
+with clauses. For EACH clause, output a risk finding.
+
+Return a JSON array. Each element has this structure:
+{
+  "clause": { "id": 1, "raw_text": "...", "clause_type": "...", ... },
+  "finding": {
+    "clause_id": 1,
+    "severity": "CRITICAL",
+    "risk_title": "Short descriptive title",
+    "risk_reason": "Specific reason citing what the clause actually says",
+    "recommended_action": "What the user should do about it"
+  }
+}
+
+SEVERITY LEVELS (use exactly one per clause):
+
+CRITICAL - Use when:
+- IP assignment covers personal work or time outside employment
+- Unlimited liability, no termination right
+- Mandatory arbitration waiving right to sue or jury trial
+- Class action waiver
+
+HIGH - Use when:
+- Non-compete over 1 year or with no geographic limit
+- Auto-renewal with no opt-out
+- Unilateral contract changes by one party
+- One-sided broad indemnification
+
+MEDIUM - Use when:
+- Standard non-compete of 1 year or less
+- Auto-renewal with 30+ day notice
+- Low liability caps
+- Net-60+ payment terms
+- Out-of-state governing law
+
+LOW - Use when:
+- Standard governing law (Delaware, NY)
+- Standard payment terms
+- Standard confidentiality
+- Standard termination notice
+
+INFO - Use when:
+- Definitions, recitals, severability, entire agreement, force majeure
+
+CRITICAL RULES:
+- Every risk_reason MUST mention specific language from the clause
+- The output MUST be a valid JSON array starting with [ and ending with ]
+- Output ONE finding per input clause — never skip any clause
+- Do NOT include any text before or after the JSON array
+"""
+
+TRANSLATOR_SYSTEM_PROMPT: str = """
+Translate legal clauses into plain English and provide negotiation help.
+
+You receive a JSON array of clauses with risk findings. For EACH clause, add:
+- plain_english: Short explanation in simple words (1-2 sentences, start with "You" or "This clause")
+- recommended_action: Specific action to take
+
+For CRITICAL and HIGH severity clauses, also add these (otherwise leave as "" and []):
+- safer_clause_version: Rewritten balanced version
+- negotiation_message: Brief email asking for the change
+- impact_scenarios: List of 2-3 real-world consequences
+
+Return the full JSON array with all fields filled. No markdown fences.
+"""
+
+REPORTER_SYSTEM_PROMPT: str = """
+Build a markdown report from scored clauses.
+
+Risk score formula: (critical*10 + high*7 + medium*4 + low*1) / total, capped at 10.
+
+Return ONLY a JSON object:
+{
+  "contract_name": "sample.txt",
+  "summary": {
+    "total_clauses": 5,
+    "critical_count": 1,
+    "high_count": 1,
+    "medium_count": 2,
+    "low_count": 1,
+    "overall_score": 4.2,
+    "contract_type": "NDA"
+  },
+  "top_3_actions": ["Action 1", "Action 2", "Action 3"],
+  "markdown_report": "full markdown text..."
+}
+
+No markdown fences. No extra text.
+"""

config/settings.py

@@ -0,0 +1,37 @@
+"""Application configuration loaded from environment variables.
+
+Supports Qwen via vLLM (default) and any OpenAI-compatible API as fallback.
+"""
+
+import os
+from typing import Final
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+API_KEY: str = os.environ.get("API_KEY", os.environ.get("DEEPSEEK_API_KEY", "EMPTY"))
+BASE_URL: str = os.environ.get(
+    "BASE_URL",
+    os.environ.get("VLLM_BASE_URL", "http://165.245.141.170:8000/v1"),
+)
+MODEL_NAME: str = os.environ.get(
+    "MODEL_NAME",
+    os.environ.get("VLLM_MODEL_NAME", "Qwen/Qwen2.5-1.5B-Instruct"),
+)
+MAX_TOKENS: Final[int] = int(os.environ.get("MAX_TOKENS", "4096"))
+TIMEOUT_SECONDS: Final[int] = int(os.environ.get("TIMEOUT_SECONDS", "120"))
+MAX_CLAUSES: Final[int] = 60
+
+TEMPERATURE: Final[float] = 0.0
+
+DEEPSEEK_API_KEY: str = API_KEY
+
+
+def validate_config() -> None:
+    """Validate that all required configuration is present.
+
+    For Qwen/vLLM, no API key is required — the check is informational.
+    Raises ValueError only if a legacy DeepSeek key is expected and missing.
+    """
+    pass

main.py

@@ -0,0 +1,98 @@
+"""ClauseGuard CLI — run the 5-agent pipeline from the command line."""
+
+import argparse
+import asyncio
+import logging
+import sys
+from pathlib import Path
+
+# Ensure parent directory is in path so `clauseguard` package is importable
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from clauseguard.agents.orchestrator import run_pipeline
+from clauseguard.config.settings import validate_config
+from clauseguard.tools.file_tools import extract_text
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
+logger = logging.getLogger(__name__)
+
+
+def main() -> None:
+    """Entry point for the ClauseGuard CLI."""
+    parser = argparse.ArgumentParser(
+        description="ClauseGuard — AI-Powered Contract Clause Risk Analyzer"
+    )
+    parser.add_argument(
+        "--file",
+        type=str,
+        required=True,
+        help="Path to the contract file (PDF, TXT, or DOCX)",
+    )
+    parser.add_argument(
+        "--output",
+        type=str,
+        default="report.md",
+        help="Path for the output markdown report (default: report.md)",
+    )
+    args = parser.parse_args()
+
+    try:
+        validate_config()
+    except ValueError as e:
+        logger.error("Configuration error: %s", e)
+        print(f"Error: {e}")
+        print("Create a .env file with your model endpoint settings or set them as environment variables.")
+        sys.exit(1)
+
+    file_path = Path(args.file)
+    if not file_path.exists():
+        logger.error("File not found: %s", file_path)
+        print(f"Error: File not found — {file_path}")
+        sys.exit(1)
+
+    try:
+        file_bytes = file_path.read_bytes()
+    except Exception as e:
+        logger.error("Failed to read file: %s", e)
+        print(f"Error: Could not read file — {e}")
+        sys.exit(1)
+
+    try:
+        raw_text = extract_text(file_bytes, file_path.name)
+    except ValueError as e:
+        logger.error("File parsing error: %s", e)
+        print(f"Error: {e}")
+        sys.exit(1)
+
+    print(f"Analyzing {file_path.name}...")
+    print()
+
+    try:
+        report = asyncio.run(run_pipeline(raw_text, file_path.name))
+    except Exception as e:
+        logger.error("Pipeline failed: %s", e)
+        print(f"Error: Analysis failed — {e}")
+        sys.exit(1)
+
+    output_path = Path(args.output)
+    try:
+        output_path.write_text(report.markdown_report, encoding="utf-8")
+    except Exception as e:
+        logger.error("Failed to write report: %s", e)
+        print(f"Error: Could not write report — {e}")
+        sys.exit(1)
+
+    print("=" * 60)
+    print(f"Report saved to: {output_path}")
+    print(f"Overall Risk Score: {report.summary.overall_score}/10")
+    print(f"Critical: {report.summary.critical_count} | High: {report.summary.high_count} | "
+          f"Medium: {report.summary.medium_count} | Low: {report.summary.low_count}")
+    print()
+    print("Top 3 Actions Before Signing:")
+    for i, action in enumerate(report.top_3_actions, 1):
+        print(f"  {i}. {action}")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

models/__init__.py

@@ -0,0 +1,18 @@
+"""ClauseGuard data models."""
+
+from clauseguard.models.clause import Clause, ClauseList, ClauseType
+from clauseguard.models.findings import RecommendedAction, RiskFinding, ScoredClause, Severity
+from clauseguard.models.report import ClauseReport, FinalReport, RiskSummary
+
+__all__ = [
+    "Clause",
+    "ClauseList",
+    "ClauseReport",
+    "ClauseType",
+    "FinalReport",
+    "RecommendedAction",
+    "RiskFinding",
+    "RiskSummary",
+    "ScoredClause",
+    "Severity",
+]

models/clause.py

@@ -0,0 +1,60 @@
+"""Pydantic models for contract clauses."""
+
+from enum import Enum
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ClauseType(str, Enum):
+    """Enumeration of clause categories found in contracts."""
+
+    NDA = "NDA"
+    IP_ASSIGNMENT = "IP_ASSIGNMENT"
+    NON_COMPETE = "NON_COMPETE"
+    ARBITRATION = "ARBITRATION"
+    AUTO_RENEWAL = "AUTO_RENEWAL"
+    LIABILITY_CAP = "LIABILITY_CAP"
+    TERMINATION = "TERMINATION"
+    DATA_SHARING = "DATA_SHARING"
+    GOVERNING_LAW = "GOVERNING_LAW"
+    PAYMENT = "PAYMENT"
+    INDEMNIFICATION = "INDEMNIFICATION"
+    OTHER = "OTHER"
+
+
+class Clause(BaseModel):
+    """A single clause extracted from a contract."""
+
+    id: int = Field(..., description="Unique clause identifier")
+    raw_text: str = Field(..., description="Original text of the clause")
+    plain_english: Optional[str] = Field(
+        None, description="Plain English translation of the clause"
+    )
+    clause_type: ClauseType = Field(
+        default=ClauseType.OTHER, description="Classified type of this clause"
+    )
+    section_heading: Optional[str] = Field(
+        None, description="Detected section heading for this clause"
+    )
+    position: int = Field(
+        ..., description="Sequential position of the clause in the document"
+    )
+    confidence_score: Optional[float] = Field(
+        None,
+        ge=0.0,
+        le=1.0,
+        description="Classifier confidence score (0.0 to 1.0) for the assigned clause type",
+    )
+
+
+class ClauseList(BaseModel):
+    """A collection of clauses extracted from a contract."""
+
+    clauses: List[Clause] = Field(
+        default_factory=list, description="List of extracted clauses"
+    )
+    contract_type: str = Field(
+        default="Other", description="Detected overall contract type"
+    )
+    total_clauses: int = Field(0, description="Total number of clauses extracted")

models/findings.py

@@ -0,0 +1,69 @@
+"""Pydantic models for risk findings and scored clauses."""
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+from clauseguard.models.clause import Clause
+
+
+class Severity(str, Enum):
+    """Enumeration of risk severity levels."""
+
+    CRITICAL = "CRITICAL"
+    HIGH = "HIGH"
+    MEDIUM = "MEDIUM"
+    LOW = "LOW"
+    INFO = "INFO"
+
+
+class RecommendedAction(BaseModel):
+    """A specific, actionable recommendation for a clause."""
+
+    action: str = Field(..., description="What to do (e.g., negotiate, remove, clarify)")
+    sample_counter_language: str = Field(
+        default="", description="Suggested alternative language for negotiation"
+    )
+    priority: int = Field(
+        default=1,
+        ge=1,
+        le=3,
+        description="Action priority: 1=do immediately, 2=strongly recommend, 3=consider",
+    )
+
+
+class RiskFinding(BaseModel):
+    """A risk finding associated with a specific clause."""
+
+    clause_id: int = Field(..., description="The ID of the clause this finding relates to")
+    severity: Severity = Field(..., description="Severity level of the risk")
+    risk_title: str = Field(..., description="Short title describing the risk")
+    risk_reason: str = Field(
+        ..., description="Detailed explanation citing what the clause actually says"
+    )
+    recommended_action: str = Field(
+        default="", description="Specific, actionable recommendation"
+    )
+    negotiation_tip: str = Field(
+        default="",
+        description="Suggested counter-language or negotiation approach for this clause",
+    )
+    safer_clause_version: str = Field(
+        default="",
+        description="A rewritten, safer version of the clause to propose",
+    )
+    negotiation_message: str = Field(
+        default="",
+        description="Email-style message the user can copy-paste to request the change",
+    )
+    impact_scenarios: list[str] = Field(
+        default_factory=list,
+        description="2-3 realistic consequences if the user signs this clause as-is",
+    )
+
+
+class ScoredClause(BaseModel):
+    """A clause paired with its risk finding."""
+
+    clause: Clause = Field(..., description="The original clause")
+    finding: RiskFinding = Field(..., description="The associated risk finding")

models/report.py

@@ -0,0 +1,69 @@
+"""Pydantic models for the final risk report."""
+
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+from clauseguard.models.findings import ScoredClause
+
+
+class ClauseReport(BaseModel):
+    """Per-clause analysis record within the final report."""
+
+    clause_number: int = Field(..., description="1-based index of clause in report")
+    clause_type: str = Field(..., description="Classified type of this clause")
+    severity: str = Field(..., description="Severity rating")
+    severity_emoji: str = Field(..., description="Emoji for severity level")
+    raw_text: str = Field(..., description="Original clause text")
+    plain_english: str = Field("", description="Plain English translation")
+    risk_title: str = Field(..., description="Risk title")
+    risk_reason: str = Field(..., description="Why this is a risk")
+    recommended_action: str = Field("", description="What to do about it")
+    negotiation_tip: Optional[str] = Field(
+        None, description="Suggested counter-language for negotiation"
+    )
+
+
+class RiskSummary(BaseModel):
+    """Summary statistics for a risk report."""
+
+    total_clauses: int = Field(0, description="Total number of clauses analyzed")
+    critical_count: int = Field(0, description="Number of CRITICAL findings")
+    high_count: int = Field(0, description="Number of HIGH findings")
+    medium_count: int = Field(0, description="Number of MEDIUM findings")
+    low_count: int = Field(0, description="Number of LOW findings")
+    overall_score: float = Field(
+        0.0, description="Overall risk score from 0 to 10 (10 = most risky)"
+    )
+    contract_type: str = Field(
+        "Other", description="The detected type of contract"
+    )
+
+
+class FinalReport(BaseModel):
+    """The complete ClauseGuard risk analysis report."""
+
+    contract_name: str = Field(..., description="Name of the analyzed contract file")
+    generated_at: datetime = Field(
+        default_factory=datetime.now, description="Timestamp when the report was generated"
+    )
+    summary: RiskSummary = Field(
+        default_factory=RiskSummary, description="Risk summary statistics"
+    )
+    top_3_actions: List[str] = Field(
+        default_factory=list, description="Top 3 recommended actions before signing"
+    )
+    scored_clauses: List[ScoredClause] = Field(
+        default_factory=list, description="All scored clauses ordered by severity"
+    )
+    markdown_report: str = Field(
+        "", description="The full report formatted as markdown"
+    )
+    processed_normally: bool = Field(
+        True,
+        description="False if the pipeline was truncated or ran with partial data",
+    )
+    truncation_note: str = Field(
+        "", description="Note about truncation if contract exceeded clause limit"
+    )

requirements.txt

@@ -0,0 +1,12 @@
+openai-agents>=0.1.0
+openai>=1.0.0
+pydantic>=2.0.0
+streamlit>=1.30.0
+PyMuPDF>=1.23.0
+pdfplumber>=0.9.0
+python-docx>=1.0.0
+python-dotenv>=1.0.0
+chardet>=5.0.0
+pytest>=7.0.0
+pytest-asyncio>=0.21.0
+Pillow>=10.0.0

sample_contracts/sample_employment.txt

@@ -0,0 +1,21 @@
+EMPLOYMENT AGREEMENT
+
+1. POSITION AND DUTIES. The Company hereby employs Employee as a Senior Software Engineer. Employee shall perform all duties and responsibilities as may be assigned by the Company from time to time. Employee agrees to devote their full working time and attention to the business of the Company.
+
+2. COMPENSATION. The Company shall pay Employee an annual salary of $120,000, payable in equal bi-weekly installments. Employee shall be eligible for an annual performance bonus at the discretion of the Company. All compensation is subject to applicable tax withholdings.
+
+3. AT-WILL EMPLOYMENT. Employee's employment with the Company is at-will, meaning that either the Company or Employee may terminate the employment relationship at any time, with or without cause or advance notice. The Company reserves the right to modify Employee's duties, compensation, and benefits at its sole discretion at any time.
+
+4. NON-COMPETITION. For a period of two (2) years following the termination of Employee's employment for any reason, Employee shall not, directly or indirectly, engage in, own, or be employed by any business that is competitive with the Company, within the United States of America. This restriction applies regardless of the geographic location of Employee's work or the Company's actual business operations.
+
+5. INTELLECTUAL PROPERTY. Employee agrees that all inventions, works of authorship, trade secrets, and other intellectual property created by Employee, whether during working hours or on Employee's own time, and whether using Company equipment or Employee's personal equipment, shall be the sole and exclusive property of the Company. Employee hereby irrevocably assigns all such intellectual property to the Company. This assignment does not have any geographic or temporal limitations.
+
+6. DISPUTE RESOLUTION. Any and all disputes arising out of Employee's employment or the termination thereof shall be resolved exclusively through binding arbitration. Employee expressly waives any right to bring a lawsuit in court and waives the right to a jury trial. Employee further waives the right to participate in or bring any class action or collective action against the Company, and agrees that all claims must be brought in Employee's individual capacity.
+
+7. NON-DISPARAGEMENT. Employee agrees not to make any statements, whether written or oral, that disparage, criticize, or negatively reflect upon the Company, its products, services, officers, directors, or employees. This obligation survives the termination of employment indefinitely.
+
+8. BENEFITS. Employee shall be eligible to participate in the Company's health insurance, retirement, and other benefit plans as they may exist from time to time. The Company reserves the right to modify, amend, or terminate any such benefit plans at any time and for any reason, without prior notice to Employee.
+
+9. CONFIDENTIALITY. Employee shall maintain the confidentiality of all Company trade secrets, customer information, business strategies, and other proprietary information both during and after employment.
+
+10. GOVERNING LAW AND SEVERABILITY. This Agreement shall be governed by the laws of the State of Delaware. If any provision is found unenforceable, the remaining provisions shall remain in effect.

sample_contracts/sample_freelance.txt

@@ -0,0 +1,17 @@
+FREELANCE SERVICES AGREEMENT
+
+1. SERVICES. Freelancer agrees to provide web development services to Client as described in the attached Statement of Work. Freelancer shall perform the services in a professional and workmanlike manner in accordance with industry standards.
+
+2. PAYMENT TERMS. Client shall pay Freelancer at the rate of $100 per hour. Invoices shall be submitted monthly, and Client shall pay all undisputed invoices within sixty (60) calendar days of receipt. Late payments shall accrue interest at the rate of 1% per month.
+
+3. OWNERSHIP OF WORK PRODUCT. All work product, deliverables, designs, code, documentation, and other materials created by Freelancer in connection with this Agreement (collectively, the "Work Product") shall be the sole and exclusive property of Client. Freelancer hereby assigns to Client all right, title, and interest in and to the Work Product, including all intellectual property rights. For the avoidance of doubt, Client shall also own any pre-existing tools, libraries, frameworks, code snippets, templates, or other materials that Freelancer incorporates into the Work Product, even if such materials were created by Freelancer prior to this Agreement.
+
+4. REVISIONS AND MODIFICATIONS. Client shall be entitled to request unlimited revisions to the Work Product at any time. Freelancer shall complete all requested revisions at no additional charge and within the timeframe reasonably specified by Client. Freelancer may not deny any revision request.
+
+5. NON-COMPETITION. During the term of this Agreement and for a period of one (1) year after its termination, Freelancer shall not provide web development or any related services to any business that offers products or services similar to Client's business, as determined by Client in its sole discretion.
+
+6. TERMINATION. Client may terminate this Agreement at any time for any reason or for no reason by providing written notice to Freelancer. Upon termination for convenience, Freelancer shall not be entitled to any kill fee, termination fee, or compensation beyond payment for hours actually worked through the date of termination. Freelancer may only terminate this Agreement for material breach by Client that remains uncured for thirty (30) days.
+
+7. GOVERNING LAW. This Agreement shall be governed by the laws of the State of California. Any legal action arising from this Agreement shall be brought exclusively in the courts located in Los Angeles County, California.
+
+8. INDEMNIFICATION. Freelancer agrees to indemnify, defend, and hold harmless Client from and against any and all claims, damages, losses, and expenses arising out of or related to Freelancer's performance of the services, including any claims that the Work Product infringes third-party intellectual property rights.

sample_contracts/sample_nda.txt

@@ -0,0 +1,21 @@
+NON-DISCLOSURE AND CONFIDENTIALITY AGREEMENT
+
+1. PARTIES. This Non-Disclosure and Confidentiality Agreement (the "Agreement") is entered into by and between Acme Corp, a Delaware corporation ("Company"), and John Doe ("Recipient"), effective as of January 1, 2024.
+
+2. DEFINITION OF CONFIDENTIAL INFORMATION. "Confidential Information" shall mean any and all information disclosed by Company to Recipient, whether in written, oral, electronic, or other form, including but not limited to: trade secrets, business plans, customer lists, financial data, product designs, source code, marketing strategies, employee information, and any other information that a reasonable person would understand to be confidential. Confidential Information also includes all information conveyed verbally that is identified as confidential at the time of disclosure, whether or not subsequently reduced to writing.
+
+3. CONFIDENTIALITY OBLIGATIONS. Recipient agrees to hold all Confidential Information in strict confidence and shall not disclose, copy, distribute, or use any Confidential Information for any purpose other than as expressly authorized by Company in writing. Recipient shall use at least the same degree of care to protect the Confidential Information as it uses to protect its own confidential information of like nature, but in no event less than reasonable care.
+
+4. NON-COMPETITION. For a period of eighteen (18) months following the termination of this Agreement, Recipient shall not, directly or indirectly, engage in, own, manage, operate, control, be employed by, consult for, or otherwise provide services to any business that is competitive with the business of Company, anywhere in the world.
+
+5. INTELLECTUAL PROPERTY ASSIGNMENT. Recipient hereby irrevocably assigns and agrees to assign to Company all right, title, and interest in and to any and all inventions, discoveries, improvements, works of authorship, trade secrets, and other intellectual property conceived, created, or reduced to practice by Recipient, whether alone or with others, during the term of this Agreement and for a period of one (1) year after its termination, regardless of whether such intellectual property was created on Recipient's own time or using Recipient's own equipment.
+
+6. DISPUTE RESOLUTION AND ARBITRATION. Any dispute, claim, or controversy arising out of or relating to this Agreement shall be resolved exclusively through binding arbitration administered by the American Arbitration Association in accordance with its Commercial Arbitration Rules. The parties expressly waive any right to a trial by jury and waive the right to participate in any class action or representative proceeding.
+
+7. GOVERNING LAW. This Agreement shall be governed by and construed in accordance with the laws of the State of New York, without regard to its conflict of laws principles. The parties agree that any legal action shall be brought exclusively in the federal or state courts located in New York County, New York.
+
+8. TERM AND AUTO-RENEWAL. This Agreement shall commence on the Effective Date and shall continue for an initial term of one (1) year. Thereafter, this Agreement shall automatically renew for successive one-year terms unless either party provides written notice of non-renewal at least ninety (90) days prior to the end of the then-current term.
+
+9. SEVERABILITY. If any provision of this Agreement is held to be invalid or unenforceable, such provision shall be modified to the minimum extent necessary to make it enforceable, and the remaining provisions shall remain in full force and effect.
+
+10. ENTIRE AGREEMENT. This Agreement constitutes the entire agreement between the parties with respect to the subject matter hereof and supersedes all prior negotiations, discussions, and agreements, whether written or oral.

services/__init__.py

@@ -0,0 +1,17 @@
+"""ClauseGuard model services package."""
+
+from clauseguard.services.model_service import (
+    call_model,
+    call_model_chat,
+    clean_json_response,
+    get_client,
+    reset_client,
+)
+
+__all__ = [
+    "call_model",
+    "call_model_chat",
+    "clean_json_response",
+    "get_client",
+    "reset_client",
+]

services/model_service.py

@@ -0,0 +1,305 @@
+"""Model service layer — unified Qwen/vLLM inference via OpenAI-compatible API.
+
+Provides a single shared client and reusable inference functions for all
+ClauseGuard agents and the copilot. Handles retries, timeouts, JSON cleaning,
+and graceful error recovery.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any, Dict, List
+
+from openai import AsyncOpenAI, OpenAI
+
+from clauseguard.config.settings import (
+    API_KEY,
+    BASE_URL,
+    MAX_TOKENS,
+    MODEL_NAME,
+    TEMPERATURE,
+    TIMEOUT_SECONDS,
+)
+
+logger = logging.getLogger(__name__)
+
+_async_client: AsyncOpenAI | None = None
+_sync_client: OpenAI | None = None
+
+
+def get_client() -> AsyncOpenAI:
+    """Return the shared AsyncOpenAI client (lazy singleton)."""
+    global _async_client
+    if _async_client is None:
+        _async_client = AsyncOpenAI(api_key=API_KEY, base_url=BASE_URL)
+    return _async_client
+
+
+def get_sync_client() -> OpenAI:
+    """Return the shared synchronous OpenAI client (lazy singleton)."""
+    global _sync_client
+    if _sync_client is None:
+        _sync_client = OpenAI(api_key=API_KEY, base_url=BASE_URL)
+    return _sync_client
+
+
+def reset_client() -> None:
+    """Reset the shared clients — useful for testing or config changes."""
+    global _async_client, _sync_client
+    _async_client = None
+    _sync_client = None
+
+
+def clean_json_response(content: str) -> str:
+    """Strip markdown fences and leading/trailing non-JSON text from LLM output."""
+    content = content.strip()
+    if content.startswith("```json"):
+        content = content[7:]
+    elif content.startswith("```"):
+        content = content[3:]
+    if content.endswith("```"):
+        content = content[:-3]
+    return content.strip()
+
+
+async def call_model(
+    system_prompt: str,
+    user_prompt: str,
+    *,
+    agent_name: str = "Agent",
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+    timeout: int | None = None,
+    max_retries: int = 1,
+    validate_json: bool = True,
+) -> str | None:
+    """Call the Qwen model with retry, timeout, and JSON validation.
+
+    Args:
+        system_prompt: The system-level instruction.
+        user_prompt: The user-level query.
+        agent_name: Label used in log messages.
+        temperature: Sampling temperature (defaults to config TEMPERATURE).
+        max_tokens: Max tokens for the response (defaults to config MAX_TOKENS).
+        timeout: Per-call timeout in seconds (defaults to config TIMEOUT_SECONDS).
+        max_retries: Number of additional retries on JSON parse failure.
+        validate_json: Whether to validate the response as valid JSON.
+
+    Returns:
+        The model's raw text response, or None if all attempts fail.
+    """
+    client = get_client()
+    temp = temperature if temperature is not None else TEMPERATURE
+    mt = max_tokens if max_tokens is not None else MAX_TOKENS
+    tout = timeout if timeout is not None else TIMEOUT_SECONDS
+
+    last_error: str | None = None
+    for attempt in range(max_retries + 1):
+        try:
+            response = await asyncio.wait_for(
+                client.chat.completions.create(
+                    model=MODEL_NAME,
+                    messages=[
+                        {"role": "system", "content": system_prompt},
+                        {"role": "user", "content": user_prompt},
+                    ],
+                    temperature=temp,
+                    max_tokens=mt,
+                ),
+                timeout=tout,
+            )
+            content = response.choices[0].message.content or ""
+            logger.info("%s received %d chars in %d attempt(s)", agent_name, len(content), attempt + 1)
+
+            if validate_json:
+                cleaned = clean_json_response(content)
+                if not cleaned or not cleaned.strip():
+                    raise ValueError("Empty response")
+                json.loads(cleaned)
+                logger.info("%s produced valid JSON", agent_name)
+            return content
+
+        except json.JSONDecodeError as e:
+            last_error = str(e)
+            preview = content[:200] if 'content' in dir() else "(no content)"
+            logger.warning("%s returned malformed JSON (attempt %d): %s | preview: %s", agent_name, attempt + 1, e, preview)
+            if attempt < max_retries:
+                logger.warning("%s returned malformed JSON, retrying...", agent_name)
+                user_prompt += "\n\nIMPORTANT: Output ONLY raw JSON. No markdown, no explanation."
+        except ValueError as e:
+            last_error = str(e)
+            if attempt < max_retries:
+                logger.warning("%s returned empty response, retrying...", agent_name)
+        except asyncio.TimeoutError:
+            logger.error("%s agent timed out after %ds", agent_name, tout)
+            return None
+        except Exception as e:
+            logger.error("%s agent failed: %s", agent_name, e)
+            return None
+
+    logger.error("%s failed to produce valid JSON: %s", agent_name, last_error)
+    return None
+
+
+async def call_model_chat(
+    messages: List[Dict[str, str]],
+    *,
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+    timeout: int = 60,
+) -> str:
+    """Call the Qwen model for chat (multi-turn conversation).
+
+    Args:
+        messages: Full message list (system + history + user).
+        temperature: Sampling temperature.
+        max_tokens: Max tokens for the response.
+        timeout: Per-call timeout in seconds.
+
+    Returns:
+        The assistant's text response, or a friendly error message.
+    """
+    client = get_client()
+    temp = temperature if temperature is not None else TEMPERATURE
+    mt = max_tokens if max_tokens is not None else MAX_TOKENS
+
+    try:
+        response = await asyncio.wait_for(
+            client.chat.completions.create(
+                model=MODEL_NAME,
+                messages=messages,
+                temperature=temp,
+                max_tokens=mt,
+            ),
+            timeout=timeout,
+        )
+        content = response.choices[0].message.content
+        return content or "I'm sorry, I couldn't generate a response. Please try again."
+    except asyncio.TimeoutError:
+        logger.error("Chat call timed out after %ds", timeout)
+        return "I'm sorry, the request timed out. Please try a shorter question or try again."
+    except Exception as e:
+        logger.error("Chat call failed: %s", e)
+        return f"I'm sorry, something went wrong: {e}"
+
+
+# ── Synchronous wrappers for use in Streamlit callbacks ──
+
+
+def call_model_chat_sync(
+    messages: List[Dict[str, str]],
+    *,
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+    timeout: int = 60,
+) -> str:
+    """Synchronous wrapper around call_model_chat for Streamlit callbacks."""
+    try:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        try:
+            result = loop.run_until_complete(
+                call_model_chat(messages, temperature=temperature, max_tokens=max_tokens, timeout=timeout)
+            )
+        finally:
+            loop.close()
+        return result
+    except Exception as e:
+        logger.error("call_model_chat_sync failed: %s", e)
+        return f"Sorry, an unexpected error occurred: {e}"
+
+
+# ── Higher-level domain functions ──
+
+
+async def analyze_clause(
+    clause_text: str,
+    clause_type: str = "",
+    additional_context: str = "",
+    system_prompt: str = "",
+    user_prompt_template: str = "",
+    agent_name: str = "Analyzer",
+) -> str | None:
+    """Analyze a single clause — used by pipeline agents.
+
+    Args:
+        clause_text: The clause raw text to analyze.
+        clause_type: Optional pre-classified clause type.
+        additional_context: Additional context to append.
+        system_prompt: The agent-specific system prompt.
+        user_prompt_template: A template string for the user prompt.
+        agent_name: Label for logging.
+
+    Returns:
+        Raw response string or None.
+    """
+    user_prompt = user_prompt_template.format(
+        clause_text=clause_text,
+        clause_type=clause_type,
+        context=additional_context,
+    ) if user_prompt_template else clause_text
+
+    return await call_model(
+        system_prompt=system_prompt,
+        user_prompt=user_prompt,
+        agent_name=agent_name,
+    )
+
+
+async def generate_negotiation_message(
+    clause_text: str,
+    risk_reason: str,
+    safer_version: str = "",
+) -> str:
+    """Generate a professional negotiation message for a risky clause."""
+    system = (
+        "You are a professional contract negotiator. Write a short, polite email "
+        "message requesting a change to a contract clause. Keep it professional, "
+        "concise, and non-confrontational. Maximum 4-5 sentences."
+    )
+    user = (
+        f"The risky clause is:\n\"{clause_text}\"\n\n"
+        f"Why it's risky:\n{risk_reason}\n\n"
+    )
+    if safer_version:
+        user += f"Suggested safer version:\n\"{safer_version}\"\n\n"
+    user += "Write a single email-style negotiation message requesting a fair revision."
+
+    result = await call_model(
+        system_prompt=system,
+        user_prompt=user,
+        agent_name="NegotiationGenerator",
+        validate_json=False,
+    )
+    return result or ""
+
+
+async def contract_chat(
+    contract_context: str,
+    chat_history: List[Dict[str, str]],
+    user_message: str,
+    system_prompt: str,
+    timeout: int = 60,
+) -> str:
+    """Handle a contract chat conversation with full contract context.
+
+    Args:
+        contract_context: The formatted contract + analysis context.
+        chat_history: Previous messages (role/content dicts).
+        user_message: The user's new question.
+        system_prompt: The copilot system prompt.
+        timeout: Per-call timeout.
+
+    Returns:
+        Assistant response string.
+    """
+    full_system = f"{system_prompt}\n\n---\n\n## CONTRACT CONTEXT\n\n{contract_context}"
+
+    messages: List[Dict[str, str]] = [{"role": "system", "content": full_system}]
+    for msg in chat_history:
+        messages.append({"role": msg["role"], "content": msg["content"]})
+    messages.append({"role": "user", "content": user_message})
+
+    return await call_model_chat(messages, timeout=timeout)

tests/test_extractor.py

@@ -0,0 +1,144 @@
+"""Tests for the Extractor agent."""
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+from clauseguard.agents.extractor import _parse_response, _validate_clause_list
+from clauseguard.models.clause import Clause, ClauseList
+
+SAMPLE_NDA_PATH = Path(__file__).parent.parent / "sample_contracts" / "sample_nda.txt"
+
+
+def load_sample_nda() -> str:
+    """Load the sample NDA text file."""
+    with open(SAMPLE_NDA_PATH, "r", encoding="utf-8") as f:
+        return f.read()
+
+
+def test_sample_nda_produces_at_least_6_clauses() -> None:
+    """Verify sample_nda.txt has enough content to produce 6+ clauses."""
+    text = load_sample_nda()
+    # The document has 10 numbered sections
+    assert len(text.split("\n")) > 20
+    # Each paragraph cluster represents a clause
+    from clauseguard.tools.clause_tools import split_into_clauses
+    clauses = split_into_clauses(text)
+    assert len(clauses) >= 6, f"Expected at least 6 clauses, got {len(clauses)}"
+
+
+def test_short_text_raises_value_error() -> None:
+    """Test that a very short document (2 sentences) raises ValueError."""
+    mock_json = json.dumps({
+        "clauses": [
+            {
+                "id": 1,
+                "raw_text": "This is a short agreement.",
+                "plain_english": None,
+                "clause_type": "OTHER",
+                "section_heading": None,
+                "position": 1,
+            },
+            {
+                "id": 2,
+                "raw_text": "Parties agree to the above.",
+                "plain_english": None,
+                "clause_type": "OTHER",
+                "section_heading": None,
+                "position": 2,
+            },
+        ],
+        "contract_type": "Other",
+        "total_clauses": 2,
+    })
+
+    clause_list = _parse_response(mock_json)
+    with pytest.raises(ValueError, match="minimum 3 clauses required"):
+        _validate_clause_list(clause_list)
+
+
+def test_output_matches_clause_list_schema() -> None:
+    """Test that parsed output matches the ClauseList Pydantic schema."""
+    mock_json = json.dumps({
+        "clauses": [
+            {
+                "id": 1,
+                "raw_text": "Employee shall maintain confidentiality of all trade secrets.",
+                "plain_english": None,
+                "clause_type": "OTHER",
+                "section_heading": "CONFIDENTIALITY",
+                "position": 1,
+            },
+            {
+                "id": 2,
+                "raw_text": "This Agreement is governed by Delaware law.",
+                "plain_english": None,
+                "clause_type": "OTHER",
+                "section_heading": "GOVERNING LAW",
+                "position": 2,
+            },
+            {
+                "id": 3,
+                "raw_text": "Either party may terminate for convenience.",
+                "plain_english": None,
+                "clause_type": "OTHER",
+                "section_heading": "TERMINATION",
+                "position": 3,
+            },
+        ],
+        "contract_type": "NDA",
+        "total_clauses": 3,
+    })
+
+    clause_list = _parse_response(mock_json)
+    assert isinstance(clause_list, ClauseList)
+    assert clause_list.total_clauses == 3
+    assert clause_list.contract_type == "NDA"
+    assert len(clause_list.clauses) == 3
+    assert all(isinstance(c, Clause) for c in clause_list.clauses)
+    assert all(c.id > 0 for c in clause_list.clauses)
+    assert all(c.raw_text for c in clause_list.clauses)
+
+
+def test_parse_response_handles_list_input() -> None:
+    """Test that _parse_response handles both list and dict input formats."""
+    list_json = json.dumps([
+        {
+            "id": 1,
+            "raw_text": "Test clause one.",
+            "plain_english": None,
+            "clause_type": "OTHER",
+            "section_heading": None,
+            "position": 1,
+        },
+        {
+            "id": 2,
+            "raw_text": "Test clause two.",
+            "plain_english": None,
+            "clause_type": "OTHER",
+            "section_heading": None,
+            "position": 2,
+        },
+        {
+            "id": 3,
+            "raw_text": "Test clause three.",
+            "plain_english": None,
+            "clause_type": "OTHER",
+            "section_heading": None,
+            "position": 3,
+        },
+    ])
+
+    clause_list = _parse_response(list_json)
+    assert clause_list.total_clauses == 3
+
+
+def test_parse_response_handles_markdown_fences() -> None:
+    """Test that markdown code fences are stripped from responses."""
+    wrapped_json = '```json\n{\n  "clauses": [\n    {"id": 1, "raw_text": "Test one.", "plain_english": null, "clause_type": "OTHER", "section_heading": null, "position": 1},\n    {"id": 2, "raw_text": "Test two.", "plain_english": null, "clause_type": "OTHER", "section_heading": null, "position": 2},\n    {"id": 3, "raw_text": "Test three.", "plain_english": null, "clause_type": "OTHER", "section_heading": null, "position": 3}\n  ],\n  "contract_type": "Other",\n  "total_clauses": 3\n}\n```'
+
+    clause_list = _parse_response(wrapped_json)
+    assert clause_list.total_clauses == 3
+    assert clause_list.clauses[0].raw_text == "Test one."

tests/test_pipeline.py

@@ -0,0 +1,186 @@
+"""Integration tests for the full 5-agent pipeline."""
+
+import json
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from clauseguard.agents.orchestrator import run_pipeline
+from clauseguard.models.findings import Severity
+from clauseguard.models.report import FinalReport
+
+SAMPLE_NDA_PATH = Path(__file__).parent.parent / "sample_contracts" / "sample_nda.txt"
+
+
+def load_sample_nda() -> str:
+    with open(SAMPLE_NDA_PATH, "r", encoding="utf-8") as f:
+        return f.read()
+
+
+def _mock_extract_response() -> str:
+    return json.dumps({
+        "clauses": [
+            {"id": 1, "raw_text": "Confidential Information shall mean any and all information disclosed.", "plain_english": None, "clause_type": "OTHER", "section_heading": "DEFINITION", "position": 1},
+            {"id": 2, "raw_text": "Recipient agrees to hold all Confidential Information in strict confidence.", "plain_english": None, "clause_type": "OTHER", "section_heading": "CONFIDENTIALITY", "position": 2},
+            {"id": 3, "raw_text": "For 18 months, Recipient shall not compete anywhere in the world.", "plain_english": None, "clause_type": "OTHER", "section_heading": "NON-COMPETE", "position": 3},
+            {"id": 4, "raw_text": "Recipient assigns all inventions including those on personal time and equipment for 1 year after.", "plain_english": None, "clause_type": "OTHER", "section_heading": "IP ASSIGNMENT", "position": 4},
+            {"id": 5, "raw_text": "All disputes resolved by binding arbitration, waives jury trial.", "plain_english": None, "clause_type": "OTHER", "section_heading": "ARBITRATION", "position": 5},
+            {"id": 6, "raw_text": "This Agreement governed by New York law.", "plain_english": None, "clause_type": "OTHER", "section_heading": "GOVERNING LAW", "position": 6},
+            {"id": 7, "raw_text": "Auto-renews for 1-year terms unless 90 days notice.", "plain_english": None, "clause_type": "OTHER", "section_heading": "AUTO-RENEWAL", "position": 7},
+            {"id": 8, "raw_text": "If any provision is invalid, the rest remains in effect.", "plain_english": None, "clause_type": "OTHER", "section_heading": "SEVERABILITY", "position": 8},
+        ],
+        "contract_type": "Other",
+        "total_clauses": 8,
+    })
+
+
+def _mock_classify_response() -> str:
+    return json.dumps({
+        "clauses": [
+            {"id": 1, "raw_text": "Confidential Information shall mean any and all information disclosed.", "plain_english": None, "clause_type": "NDA", "section_heading": "DEFINITION", "position": 1},
+            {"id": 2, "raw_text": "Recipient agrees to hold all Confidential Information in strict confidence.", "plain_english": None, "clause_type": "NDA", "section_heading": "CONFIDENTIALITY", "position": 2},
+            {"id": 3, "raw_text": "For 18 months, Recipient shall not compete anywhere in the world.", "plain_english": None, "clause_type": "NON_COMPETE", "section_heading": "NON-COMPETE", "position": 3},
+            {"id": 4, "raw_text": "Recipient assigns all inventions including those on personal time and equipment for 1 year after.", "plain_english": None, "clause_type": "IP_ASSIGNMENT", "section_heading": "IP ASSIGNMENT", "position": 4},
+            {"id": 5, "raw_text": "All disputes resolved by binding arbitration, waives jury trial.", "plain_english": None, "clause_type": "ARBITRATION", "section_heading": "ARBITRATION", "position": 5},
+            {"id": 6, "raw_text": "This Agreement governed by New York law.", "plain_english": None, "clause_type": "GOVERNING_LAW", "section_heading": "GOVERNING LAW", "position": 6},
+            {"id": 7, "raw_text": "Auto-renews for 1-year terms unless 90 days notice.", "plain_english": None, "clause_type": "AUTO_RENEWAL", "section_heading": "AUTO-RENEWAL", "position": 7},
+            {"id": 8, "raw_text": "If any provision is invalid, the rest remains in effect.", "plain_english": None, "clause_type": "OTHER", "section_heading": "SEVERABILITY", "position": 8},
+        ],
+        "contract_type": "NDA",
+        "total_clauses": 8,
+    })
+
+
+def _mock_score_response() -> str:
+    return json.dumps([
+        {"clause": {"id": 1, "raw_text": "Confidential Information shall mean any and all information disclosed.", "plain_english": None, "clause_type": "NDA", "section_heading": "DEFINITION", "position": 1}, "finding": {"clause_id": 1, "severity": "INFO", "risk_title": "Broad Definition", "risk_reason": "Standard.", "recommended_action": ""}},
+        {"clause": {"id": 2, "raw_text": "Recipient agrees to hold all Confidential Information in strict confidence.", "plain_english": None, "clause_type": "NDA", "section_heading": "CONFIDENTIALITY", "position": 2}, "finding": {"clause_id": 2, "severity": "LOW", "risk_title": "Standard Confidentiality", "risk_reason": "Standard.", "recommended_action": ""}},
+        {"clause": {"id": 3, "raw_text": "For 18 months, Recipient shall not compete anywhere in the world.", "plain_english": None, "clause_type": "NON_COMPETE", "section_heading": "NON-COMPETE", "position": 3}, "finding": {"clause_id": 3, "severity": "HIGH", "risk_title": "Global Non-Compete", "risk_reason": "Worldwide scope.", "recommended_action": ""}},
+        {"clause": {"id": 4, "raw_text": "Recipient assigns all inventions including those on personal time and equipment for 1 year after.", "plain_english": None, "clause_type": "IP_ASSIGNMENT", "section_heading": "IP ASSIGNMENT", "position": 4}, "finding": {"clause_id": 4, "severity": "CRITICAL", "risk_title": "IP Assignment of Personal Work", "risk_reason": "Assigns all IP.", "recommended_action": ""}},
+        {"clause": {"id": 5, "raw_text": "All disputes resolved by binding arbitration, waives jury trial.", "plain_english": None, "clause_type": "ARBITRATION", "section_heading": "ARBITRATION", "position": 5}, "finding": {"clause_id": 5, "severity": "HIGH", "risk_title": "Mandatory Arbitration", "risk_reason": "Mandatory arbitration.", "recommended_action": ""}},
+        {"clause": {"id": 6, "raw_text": "This Agreement governed by New York law.", "plain_english": None, "clause_type": "GOVERNING_LAW", "section_heading": "GOVERNING LAW", "position": 6}, "finding": {"clause_id": 6, "severity": "LOW", "risk_title": "Standard Governing Law", "risk_reason": "Standard NY law.", "recommended_action": ""}},
+        {"clause": {"id": 7, "raw_text": "Auto-renews for 1-year terms unless 90 days notice.", "plain_english": None, "clause_type": "AUTO_RENEWAL", "section_heading": "AUTO-RENEWAL", "position": 7}, "finding": {"clause_id": 7, "severity": "MEDIUM", "risk_title": "Auto-Renewal", "risk_reason": "90-day notice.", "recommended_action": ""}},
+        {"clause": {"id": 8, "raw_text": "If any provision is invalid, the rest remains in effect.", "plain_english": None, "clause_type": "OTHER", "section_heading": "SEVERABILITY", "position": 8}, "finding": {"clause_id": 8, "severity": "INFO", "risk_title": "Standard Severability", "risk_reason": "Standard.", "recommended_action": ""}},
+    ])
+
+
+def _mock_translate_response() -> str:
+    return json.dumps([
+        {"clause": {"id": 1, "raw_text": "Confidential Information shall mean any and all information disclosed.", "clause_type": "NDA", "section_heading": "DEFINITION", "position": 1, "plain_english": "Defines confidential info."}, "finding": {"clause_id": 1, "severity": "INFO", "risk_title": "Broad Definition", "risk_reason": "Standard.", "recommended_action": "No action."}},
+        {"clause": {"id": 2, "raw_text": "Recipient agrees to hold all Confidential Information in strict confidence.", "clause_type": "NDA", "section_heading": "CONFIDENTIALITY", "position": 2, "plain_english": "Keep info secret."}, "finding": {"clause_id": 2, "severity": "LOW", "risk_title": "Standard Confidentiality", "risk_reason": "Standard.", "recommended_action": "No action."}},
+        {"clause": {"id": 3, "raw_text": "For 18 months, Recipient shall not compete anywhere in the world.", "clause_type": "NON_COMPETE", "section_heading": "NON-COMPETE", "position": 3, "plain_english": "No competing worldwide for 18 months."}, "finding": {"clause_id": 3, "severity": "HIGH", "risk_title": "Global Non-Compete", "risk_reason": "Worldwide.", "recommended_action": "Reduce scope."}},
+        {"clause": {"id": 4, "raw_text": "Recipient assigns all inventions including those on personal time and equipment for 1 year after.", "clause_type": "IP_ASSIGNMENT", "section_heading": "IP ASSIGNMENT", "position": 4, "plain_english": "You give all inventions to company."}, "finding": {"clause_id": 4, "severity": "CRITICAL", "risk_title": "IP Assignment of Personal Work", "risk_reason": "Assigns all IP.", "recommended_action": "Add carve-out."}},
+        {"clause": {"id": 5, "raw_text": "All disputes resolved by binding arbitration, waives jury trial.", "clause_type": "ARBITRATION", "section_heading": "ARBITRATION", "position": 5, "plain_english": "Must use arbitration."}, "finding": {"clause_id": 5, "severity": "HIGH", "risk_title": "Mandatory Arbitration", "risk_reason": "Mandatory.", "recommended_action": "Add opt-out."}},
+        {"clause": {"id": 6, "raw_text": "This Agreement governed by New York law.", "clause_type": "GOVERNING_LAW", "section_heading": "GOVERNING LAW", "position": 6, "plain_english": "NY law applies."}, "finding": {"clause_id": 6, "severity": "LOW", "risk_title": "Standard Governing Law", "risk_reason": "Standard.", "recommended_action": "No action."}},
+        {"clause": {"id": 7, "raw_text": "Auto-renews for 1-year terms unless 90 days notice.", "clause_type": "AUTO_RENEWAL", "section_heading": "AUTO-RENEWAL", "position": 7, "plain_english": "Auto-renews yearly."}, "finding": {"clause_id": 7, "severity": "MEDIUM", "risk_title": "Auto-Renewal", "risk_reason": "Auto.", "recommended_action": "Track."}},
+        {"clause": {"id": 8, "raw_text": "If any provision is invalid, the rest remains in effect.", "clause_type": "OTHER", "section_heading": "SEVERABILITY", "position": 8, "plain_english": "Invalid parts don't invalidate rest."}, "finding": {"clause_id": 8, "severity": "INFO", "risk_title": "Standard Severability", "risk_reason": "Standard.", "recommended_action": "No action."}},
+    ])
+
+
+_MOCK_RESPONSES = [
+    _mock_extract_response(),
+    _mock_classify_response(),
+    _mock_score_response(),
+    _mock_translate_response(),
+]
+
+_AGENT_CALL_MODEL_PATHS = [
+    "clauseguard.agents.extractor.call_model",
+    "clauseguard.agents.classifier.call_model",
+    "clauseguard.agents.risk_scorer.call_model",
+    "clauseguard.agents.translator.call_model",
+]
+
+
+@pytest.mark.asyncio
+async def test_pipeline_returns_final_report() -> None:
+    text = load_sample_nda()
+    results_iter = iter(_MOCK_RESPONSES)
+
+    async def mock_call_model(**kwargs):
+        try:
+            return next(results_iter)
+        except StopIteration:
+            return None
+
+    patches = [patch(path, side_effect=mock_call_model) for path in _AGENT_CALL_MODEL_PATHS]
+    for p in patches:
+        p.start()
+    try:
+        report = await run_pipeline(text, "sample_nda.txt")
+    finally:
+        for p in patches:
+            p.stop()
+
+    assert isinstance(report, FinalReport)
+    assert report.contract_name == "sample_nda.txt"
+
+
+@pytest.mark.asyncio
+async def test_pipeline_finds_critical_or_high() -> None:
+    text = load_sample_nda()
+    results_iter = iter(_MOCK_RESPONSES)
+
+    async def mock_call_model(**kwargs):
+        try:
+            return next(results_iter)
+        except StopIteration:
+            return None
+
+    patches = [patch(path, side_effect=mock_call_model) for path in _AGENT_CALL_MODEL_PATHS]
+    for p in patches:
+        p.start()
+    try:
+        report = await run_pipeline(text, "sample_nda.txt")
+    finally:
+        for p in patches:
+            p.stop()
+
+    assert isinstance(report, FinalReport)
+    assert report.summary.critical_count >= 1 or report.summary.high_count >= 1, (
+        f"Expected at least 1 CRITICAL or HIGH finding"
+    )
+
+
+@pytest.mark.asyncio
+async def test_markdown_report_is_non_empty() -> None:
+    text = load_sample_nda()
+    results_iter = iter(_MOCK_RESPONSES)
+
+    async def mock_call_model(**kwargs):
+        try:
+            return next(results_iter)
+        except StopIteration:
+            return None
+
+    patches = [patch(path, side_effect=mock_call_model) for path in _AGENT_CALL_MODEL_PATHS]
+    for p in patches:
+        p.start()
+    try:
+        report = await run_pipeline(text, "sample_nda.txt")
+    finally:
+        for p in patches:
+            p.stop()
+
+    assert isinstance(report.markdown_report, str)
+    assert len(report.markdown_report) > 0
+
+
+@pytest.mark.asyncio
+async def test_pipeline_handles_extractor_failure_gracefully() -> None:
+    text = "too short"
+
+    async def mock_call_model(**kwargs):
+        return None
+
+    patches = [patch(path, side_effect=mock_call_model) for path in _AGENT_CALL_MODEL_PATHS]
+    for p in patches:
+        p.start()
+    try:
+        report = await run_pipeline(text, "test.txt")
+    finally:
+        for p in patches:
+            p.stop()
+
+    assert isinstance(report, FinalReport)

tests/test_risk_scorer.py

@@ -0,0 +1,149 @@
+"""Tests for the Risk Scorer agent."""
+
+import json
+
+import pytest
+
+from clauseguard.agents.risk_scorer import _parse_response
+from clauseguard.models.findings import ScoredClause, Severity
+
+
+def _make_mock_response(clauses_data: list) -> str:
+    """Build a mock LLM JSON response string for testing."""
+    return json.dumps(clauses_data)
+
+
+def test_ip_assignment_clause_is_critical() -> None:
+    """Test that IP assignment of personal time/side projects is rated CRITICAL."""
+    mock_response = _make_mock_response([
+        {
+            "clause": {
+                "id": 1,
+                "raw_text": "Employee hereby assigns to Company all inventions and intellectual property created by Employee, whether during working hours or on Employee's own time, using Company equipment or Employee's personal equipment.",
+                "plain_english": None,
+                "clause_type": "IP_ASSIGNMENT",
+                "section_heading": "INTELLECTUAL PROPERTY",
+                "position": 1,
+            },
+            "finding": {
+                "clause_id": 1,
+                "severity": "CRITICAL",
+                "risk_title": "IP Assignment of Personal Work",
+                "risk_reason": "This clause claims ownership of all employee creations including those made on personal time and equipment with no carve-out for unrelated work.",
+                "recommended_action": "",
+            },
+        }
+    ])
+
+    scored = _parse_response(mock_response)
+    assert len(scored) == 1
+    assert scored[0].finding.severity == Severity.CRITICAL
+    assert scored[0].clause.clause_type.value == "IP_ASSIGNMENT"
+
+
+def test_governing_law_clause_is_low_or_info() -> None:
+    """Test that a standard governing law clause is rated LOW or INFO."""
+    mock_response = _make_mock_response([
+        {
+            "clause": {
+                "id": 1,
+                "raw_text": "This Agreement shall be governed by and construed in accordance with the laws of the State of Delaware.",
+                "plain_english": None,
+                "clause_type": "GOVERNING_LAW",
+                "section_heading": "GOVERNING LAW",
+                "position": 1,
+            },
+            "finding": {
+                "clause_id": 1,
+                "severity": "LOW",
+                "risk_title": "Standard Governing Law",
+                "risk_reason": "Standard governing law clause selecting Delaware, a common jurisdiction.",
+                "recommended_action": "",
+            },
+        }
+    ])
+
+    scored = _parse_response(mock_response)
+    assert len(scored) == 1
+    assert scored[0].finding.severity in (Severity.LOW, Severity.INFO)
+
+
+def test_every_scored_clause_has_non_empty_risk_reason() -> None:
+    """Test that every ScoredClause has a non-empty risk_reason."""
+    mock_response = _make_mock_response([
+        {
+            "clause": {
+                "id": 1,
+                "raw_text": "For two years, Employee shall not compete with Company anywhere in the United States.",
+                "plain_english": None,
+                "clause_type": "NON_COMPETE",
+                "section_heading": "NON-COMPETE",
+                "position": 1,
+            },
+            "finding": {
+                "clause_id": 1,
+                "severity": "CRITICAL",
+                "risk_title": "Overly Broad Non-Compete",
+                "risk_reason": "Non-compete duration of 2 years covers the entire US with no geographic relevance to Company's actual operations.",
+                "recommended_action": "",
+            },
+        },
+        {
+            "clause": {
+                "id": 2,
+                "raw_text": "Notice shall be sent to the address listed above.",
+                "plain_english": None,
+                "clause_type": "OTHER",
+                "section_heading": "NOTICES",
+                "position": 2,
+            },
+            "finding": {
+                "clause_id": 2,
+                "severity": "INFO",
+                "risk_title": "Standard Notice Provision",
+                "risk_reason": "Boilerplate notice provision with no unusual terms.",
+                "recommended_action": "",
+            },
+        },
+    ])
+
+    scored = _parse_response(mock_response)
+    assert len(scored) == 2
+    for sc in scored:
+        assert sc.finding.risk_reason, f"Clause {sc.clause.id} has empty risk_reason"
+        assert len(sc.finding.risk_reason) > 5
+
+
+def test_multiple_severity_levels() -> None:
+    """Test that different severities are correctly parsed."""
+    mock_response = _make_mock_response([
+        {
+            "clause": {
+                "id": i,
+                "raw_text": f"Test clause {i}",
+                "plain_english": None,
+                "clause_type": "OTHER",
+                "section_heading": None,
+                "position": i,
+            },
+            "finding": {
+                "clause_id": i,
+                "severity": sev.value,
+                "risk_title": f"Risk {i}",
+                "risk_reason": f"Reason for clause {i}",
+                "recommended_action": "",
+            },
+        }
+        for i, sev in enumerate(
+            [Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM, Severity.LOW, Severity.INFO], 1
+        )
+    ])
+
+    scored = _parse_response(mock_response)
+    assert len(scored) == 5
+    severities = [sc.finding.severity for sc in scored]
+    assert Severity.CRITICAL in severities
+    assert Severity.HIGH in severities
+    assert Severity.MEDIUM in severities
+    assert Severity.LOW in severities
+    assert Severity.INFO in severities

tools/__init__.py

@@ -0,0 +1,21 @@
+"""ClauseGuard tools package."""
+
+from clauseguard.tools.clause_tools import clean_text, detect_contract_type, detect_headings, split_into_clauses
+from clauseguard.tools.file_tools import detect_encoding, extract_text, read_docx, read_pdf, read_txt
+from clauseguard.tools.report_tools import format_markdown, risk_color, severity_badge, severity_emoji
+
+__all__ = [
+    "clean_text",
+    "detect_contract_type",
+    "detect_encoding",
+    "detect_headings",
+    "extract_text",
+    "format_markdown",
+    "read_docx",
+    "read_pdf",
+    "read_txt",
+    "risk_color",
+    "severity_badge",
+    "severity_emoji",
+    "split_into_clauses",
+]

tools/clause_tools.py

@@ -0,0 +1,133 @@
+"""Clause processing utility functions."""
+
+import re
+from typing import List
+
+
+def split_into_clauses(text: str) -> List[str]:
+    """Split a contract document into individual clauses.
+
+    Splits on: numbered patterns (1., 1.1, Article 1, Section 1, etc.),
+    ALL CAPS headings, and double newline breaks.
+
+    Args:
+        text: The full text of the contract document.
+
+    Returns:
+        A list of non-empty clause strings.
+    """
+    if not text or not text.strip():
+        return []
+
+    _paragraphs = _split_by_numbered_headings(text)
+    clauses: List[str] = []
+
+    for para in _paragraphs:
+        sub_clauses = _split_by_double_newlines(para)
+        clauses.extend(c for c in sub_clauses if c.strip())
+
+    return [c for c in clauses if len(c.split()) >= 5]
+
+
+def _split_by_numbered_headings(text: str) -> List[str]:
+    """Split text by numbered section patterns and ALL CAPS headings."""
+    pattern = r"(?:(?<=\n)\s*(?:Article|Section|SECTION|ARTICLE)\s+\d+[\.:\s]|\n\s*(?:\d+[\.\)]\s*[A-Z]|\d+\.\d+\s+[A-Z]|[IVX]+\.\s+[A-Z])|\n\s*[A-Z][A-Z\s]{10,}\n)"
+    parts = re.split(pattern, text)
+    return [p.strip() for p in parts if p.strip()]
+
+
+def _split_by_double_newlines(text: str) -> List[str]:
+    """Split text by double newline breaks."""
+    parts = re.split(r"\n\s*\n", text)
+    return [p.strip() for p in parts if p.strip()]
+
+
+def clean_text(text: str) -> str:
+    """Clean and normalize text by removing excessive whitespace.
+
+    Args:
+        text: Raw text to clean.
+
+    Returns:
+        Cleaned and normalized text.
+    """
+    if not text:
+        return ""
+
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    text = re.sub(r" {2,}", " ", text)
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    text = re.sub(r"\t+", " ", text)
+    text = re.sub(r" +\n", "\n", text)
+    text = re.sub(r"\n +", "\n", text)
+    return text.strip()
+
+
+_CONTRACT_KEYWORDS: dict[str, List[str]] = {
+    "NDA": ["non-disclosure", "confidential", "confidentiality", "trade secret", "nda", "non disclosure"],
+    "Employment": ["employment", "employee", "salary", "benefits", "at-will", "at will", "offer letter"],
+    "Freelance": ["freelance", "independent contractor", "consultant", "statement of work", "contractor"],
+    "SaaS": ["software as a service", "subscription", "saas", "service level agreement", "sla", "license"],
+}
+
+
+def detect_contract_type(text: str) -> str:
+    """Detect the type of contract based on keyword analysis.
+
+    Args:
+        text: The full text of the contract document.
+
+    Returns:
+        Detected contract type string (NDA, Employment, Freelance, SaaS, or Other).
+    """
+    if not text:
+        return "Other"
+
+    text_lower = text.lower()
+    scores: dict[str, int] = {}
+
+    for contract_type, keywords in _CONTRACT_KEYWORDS.items():
+        score = sum(1 for kw in keywords if kw in text_lower)
+        if score > 0:
+            scores[contract_type] = score
+
+    if not scores:
+        return "Other"
+
+    return max(scores, key=lambda k: scores[k])
+
+
+def detect_headings(text: str) -> list[str]:
+    """Detect section headings from a contract document.
+
+    Identifies ALL CAPS lines and numbered section headers.
+
+    Args:
+        text: The full text of the contract document.
+
+    Returns:
+        A list of detected heading strings.
+    """
+    if not text:
+        return []
+
+    headings: list[str] = []
+    lines = text.split("\n")
+
+    for line in lines:
+        stripped = line.strip()
+        if not stripped:
+            continue
+
+        if re.match(r"^\s*(?:Article|Section|SECTION|ARTICLE)\s+\d+", stripped):
+            headings.append(stripped)
+            continue
+
+        if re.match(r"^\s*\d+[\.\)]\s+[A-Z]", stripped):
+            headings.append(stripped)
+            continue
+
+        if re.match(r"^[A-Z][A-Z\s]{10,}$", stripped) and len(stripped.split()) <= 6:
+            headings.append(stripped)
+
+    return headings

tools/file_tools.py

@@ -0,0 +1,178 @@
+"""File parsing utilities for contract documents."""
+
+import io
+from typing import Union
+
+import chardet
+
+
+def read_pdf(file_bytes: bytes) -> str:
+    """Extract text from a PDF file using PyMuPDF.
+
+    Falls back to pdfplumber if PyMuPDF extraction returns empty.
+
+    Args:
+        file_bytes: Raw bytes of the PDF file.
+
+    Returns:
+        Extracted text content as a string.
+
+    Raises:
+        ValueError: If the PDF cannot be read or contains no extractable text.
+    """
+    import fitz
+
+    try:
+        doc = fitz.open(stream=file_bytes, filetype="pdf")
+    except Exception as e:
+        raise ValueError(f"Unable to open PDF file: {e}") from e
+
+    text_parts: list[str] = []
+    for page in doc:
+        text_parts.append(page.get_text())
+
+    doc.close()
+    result = "\n".join(text_parts).strip()
+
+    if result:
+        return result
+
+    result = _read_pdf_with_pdfplumber(file_bytes)
+    if result:
+        return result
+
+    raise ValueError("PDF file contains no extractable text — try pasting the text directly")
+
+
+def _read_pdf_with_pdfplumber(file_bytes: bytes) -> str:
+    """Fallback PDF extraction using pdfplumber."""
+    try:
+        import pdfplumber
+    except ImportError:
+        return ""
+
+    try:
+        with pdfplumber.open(io.BytesIO(file_bytes)) as pdf:
+            text_parts: list[str] = []
+            for page in pdf.pages:
+                page_text = page.extract_text()
+                if page_text:
+                    text_parts.append(page_text)
+        return "\n".join(text_parts).strip()
+    except Exception:
+        return ""
+
+
+def read_docx(file_bytes: bytes) -> str:
+    """Extract text from a DOCX file using python-docx.
+
+    Args:
+        file_bytes: Raw bytes of the DOCX file.
+
+    Returns:
+        Extracted text content as a string.
+
+    Raises:
+        ValueError: If the DOCX cannot be read or contains no text.
+    """
+    from docx import Document
+
+    try:
+        doc = Document(io.BytesIO(file_bytes))
+    except Exception as e:
+        raise ValueError(f"Unable to open DOCX file: {e}") from e
+
+    paragraphs: list[str] = []
+    for para in doc.paragraphs:
+        if para.text.strip():
+            paragraphs.append(para.text)
+
+    result = "\n".join(paragraphs).strip()
+
+    if not result:
+        raise ValueError("DOCX file contains no extractable text")
+
+    return result
+
+
+def detect_encoding(file_bytes: bytes) -> str:
+    """Detect the character encoding of a byte string using chardet.
+
+    Args:
+        file_bytes: Raw bytes to detect encoding for.
+
+    Returns:
+        Detected encoding name string (e.g., 'utf-8', 'latin-1').
+    """
+    detection = chardet.detect(file_bytes)
+    return detection.get("encoding", "utf-8") or "utf-8"
+
+
+def read_txt(file_bytes: bytes) -> str:
+    """Read a plain text file with automatic encoding detection.
+
+    Args:
+        file_bytes: Raw bytes of the text file.
+
+    Returns:
+        Decoded text content as a string.
+
+    Raises:
+        ValueError: If the file cannot be decoded or is empty.
+    """
+    encoding = detect_encoding(file_bytes)
+
+    try:
+        text = file_bytes.decode(encoding)
+    except (UnicodeDecodeError, LookupError):
+        text = file_bytes.decode("utf-8", errors="replace")
+
+    result = text.strip()
+
+    if not result:
+        raise ValueError("Text file is empty or contains no readable content")
+
+    return result
+
+
+SUPPORTED_EXTENSIONS = frozenset({".pdf", ".txt", ".docx"})
+READER_MAP = {
+    ".pdf": read_pdf,
+    ".txt": read_txt,
+    ".docx": read_docx,
+}
+
+
+def extract_text(file_bytes: bytes, filename: str) -> str:
+    """Route file to the appropriate reader based on extension.
+
+    Args:
+        file_bytes: Raw bytes of the file.
+        filename: Original filename used to determine file type.
+
+    Returns:
+        Extracted text content as a string.
+
+    Raises:
+        ValueError: If the file extension is not supported or the file is unreadable.
+    """
+    if not filename:
+        raise ValueError("Filename is required to determine file type")
+
+    ext = _get_extension(filename)
+
+    if ext not in READER_MAP:
+        raise ValueError(
+            f"Unsupported file type: {ext}. Supported types: {', '.join(sorted(SUPPORTED_EXTENSIONS))}"
+        )
+
+    reader = READER_MAP[ext]
+    return reader(file_bytes)
+
+
+def _get_extension(filename: str) -> str:
+    """Extract the lowercase file extension from a filename."""
+    dot_index = filename.rfind(".")
+    if dot_index == -1 or dot_index == len(filename) - 1:
+        raise ValueError(f"Cannot determine file type from filename: {filename}")
+    return filename[dot_index:].lower()

tools/report_tools.py

@@ -0,0 +1,84 @@
+"""Report formatting utilities for ClauseGuard."""
+
+from clauseguard.models.findings import Severity
+from clauseguard.models.report import FinalReport
+
+SEVERITY_EMOJI_MAP = {
+    Severity.CRITICAL: "🔴",
+    Severity.HIGH: "🟠",
+    Severity.MEDIUM: "🟡",
+    Severity.LOW: "🟢",
+    Severity.INFO: "ℹ️",
+}
+
+SEVERITY_COLOR_MAP = {
+    Severity.CRITICAL: "#FF0000",
+    Severity.HIGH: "#FF8C00",
+    Severity.MEDIUM: "#FFD700",
+    Severity.LOW: "#32CD32",
+    Severity.INFO: "#1E90FF",
+}
+
+
+def severity_badge(severity: Severity) -> str:
+    """Return the emoji badge for a severity level.
+
+    Alias for severity_emoji — matches PRD specification.
+
+    Args:
+        severity: The Severity enum value.
+
+    Returns:
+        The corresponding emoji string.
+    """
+    return SEVERITY_EMOJI_MAP.get(severity, "⚪")
+
+
+def severity_emoji(severity: Severity) -> str:
+    """Return the emoji representation for a severity level.
+
+    Args:
+        severity: The Severity enum value.
+
+    Returns:
+        The corresponding emoji string.
+    """
+    return severity_badge(severity)
+
+
+def risk_color(severity: Severity) -> str:
+    """Return the hex color code for a severity level.
+
+    Alias for severity_color — matches PRD specification.
+
+    Args:
+        severity: The Severity enum value.
+
+    Returns:
+        The corresponding hex color string.
+    """
+    return SEVERITY_COLOR_MAP.get(severity, "#808080")
+
+
+def severity_color(severity: Severity) -> str:
+    """Return the hex color code for a severity level.
+
+    Args:
+        severity: The Severity enum value.
+
+    Returns:
+        The corresponding hex color string.
+    """
+    return risk_color(severity)
+
+
+def format_markdown(report: FinalReport) -> str:
+    """Convert a FinalReport to a formatted markdown string.
+
+    Args:
+        report: The FinalReport to format.
+
+    Returns:
+        The fully formatted markdown report string.
+    """
+    return report.markdown_report