Sync from GitHub repo - 2025-09-20 22:01:48

.env.example

@@ -0,0 +1,27 @@
+# Environment variables required for Naexya Docs AI to connect with supported
+# AI service providers. Copy this file to `.env` and replace placeholder values
+# with your actual API credentials before running the application.
+
+# OpenAI powers GPT-based specification assistance, such as drafting or
+# reviewing requirement documents.
+OPENAI_API_KEY=your_openai_key_here
+
+# Anthropic enables access to Claude models for alternative language model
+# support and redundancy across AI providers.
+ANTHROPIC_API_KEY=your_anthropic_key_here
+
+# Google provides Gemini (and related) generative AI capabilities used for
+# advanced specification analysis and summarization features.
+GOOGLE_API_KEY=your_google_key_here
+
+# xAI delivers access to models like Grok for experimentation and fallback
+# options when other providers are unavailable.
+XAI_API_KEY=your_xai_key_here
+
+# Moonshot offers specialized AI models tailored for technical documentation
+# and domain-specific reasoning tasks.
+MOONSHOT_API_KEY=your_moonshot_key_here
+
+# Qwen supplies open-source-friendly large language models that can be used for
+# cost-effective or on-premise specification processing.
+QWEN_API_KEY=your_qwen_key_here

.gitignore

@@ -0,0 +1,39 @@
+# Environment variables and secrets
+.env
+*.key
+secrets/
+
+# Python build artefacts and bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Local virtual environment folders
+env/
+venv/
+ENV/
+
+# SQLite and other local database files
+*.db
+*.sqlite
+*.sqlite3
+
+# IDE and editor specific files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Operating system generated files
+.DS_Store
+Thumbs.db
+
+# Gradio generated assets
+gradio_cached_examples/
+flagged/
+
+# Log files and directories
+*.log
+logs/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Naexya
+
+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,14 +1,168 @@
+# Naexya Docs AI
+
+Open-source AI-powered specification management tool that helps product and engineering teams collaborate with multiple large language models, extract structured requirements, and export professional documentation without leaving a browser tab.
+
+---
+
+## Features
+
+- **Multi-provider AI integration** (OpenAI, Anthropic, Google, xAI, Moonshot, Qwen) with a unified client and per-provider rate limit awareness.
+- **Dual AI personas** (Requirements Specialist + Technical Architect) designed to capture business context and technical design details in parallel.
+- **Conversation-based specification extraction** that promotes iterative refinement and transparent traceability back to the originating chat history.
+- **Validation workflow for quality control** so human reviewers can approve or reject generated specifications before they become canonical.
+- **Professional export to HTML/Markdown** leveraging branded templates optimised for stakeholders and AI coding agents alike.
+- **Local SQLite storage (no cloud dependencies)** providing self-hosted data retention with optional demo seed data for evaluation.
+- **Bring-your-own-API-key model** ensuring you retain full control over model usage, quotas, and billing across all supported vendors.
+
+---
+
+## Quick Start
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/your-org/NaexyaDocsAI.git
+   cd NaexyaDocsAI
+   ```
+2. **Create an isolated environment (recommended)**
+   ```bash
+   python3 -m venv .venv
+   source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
+   ```
+3. **Install dependencies**
+   ```bash
+   pip install --upgrade pip
+   pip install -r requirements.txt
+   ```
+4. **Copy environment template and add your API keys**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your provider keys
+   ```
+5. **Launch the Gradio application**
+   ```bash
+   python app.py
+   ```
+6. **Open the local URL** printed by Gradio (typically `http://127.0.0.1:7860/`) to start collaborating with the personas and managing specifications.
+
+> 💡 **Tip:** If you do not yet have API keys, enable the built-in demo data from the landing page. This allows you to explore the interface, validation queue, and export flows without making external API calls.
+
+---
+
+## Configuration
+
+The platform is fully configurable through `config.py` and environment variables loaded from `.env`. Each provider entry defines endpoints, default parameters, and header templates to help you stay within rate limits.
+
+### Environment Variables
+
+| Variable | Description |
+| --- | --- |
+| `OPENAI_API_KEY` | Secret key for OpenAI GPT-5 endpoints. |
+| `ANTHROPIC_API_KEY` | Authentication token for Claude models. |
+| `GOOGLE_API_KEY` | Google AI Studio API key for Gemini models. |
+| `XAI_API_KEY` | API key for xAI Grok models. |
+| `MOONSHOT_API_KEY` | Credential for Moonshot (Kimi) access. |
+| `QWEN_API_KEY` | Access token for Alibaba Qwen models. |
+
+> ⚠️ Keep the `.env` file out of version control. Only `.env.example` should be committed.
+
+### Provider Setup Details
+
+1. **OpenAI (GPT-5)**
+   - Create or reuse an OpenAI account and generate a key from the dashboard.
+   - Ensure the `https://api.openai.com/v1/chat/completions` endpoint is enabled for your organisation.
+   - Optional parameters such as `temperature` and `max_tokens` can be fine-tuned in `config.py`.
+
+2. **Anthropic (Claude-4-Sonnet)**
+   - Request access to Claude-4 via the Anthropic console.
+   - Place the key in `.env` as `ANTHROPIC_API_KEY`.
+   - Respect the token per-minute limits published in the console; the defaults in `config.py` reflect conservative usage.
+
+3. **Google (Gemini-2.5-Pro)**
+   - Enable the Generative Language API in Google Cloud and create credentials through Google AI Studio.
+   - Set `GOOGLE_API_KEY` and confirm the project has the `models.generateContent` permission.
+
+4. **xAI (Grok-4-Fast)**
+   - Obtain access from the xAI developer portal and generate an API key.
+   - Update `.env` with `XAI_API_KEY`; the client automatically adds the `x-api-key` header required by Grok.
+
+5. **Moonshot (Kimi-K2)**
+   - Sign in to Moonshot AI, subscribe to the Kimi API plan, and generate a token.
+   - Store the token in `MOONSHOT_API_KEY`; the client converts payloads to the Moonshot JSON schema for you.
+
+6. **Qwen (Qwen3-Next)**
+   - Activate DashScope and retrieve a key with text-generation permissions.
+   - Save the key as `QWEN_API_KEY`; the integration handles the `Authorization: Bearer` header format.
+
+After updating `.env`, restart the application so that Gradio reloads the configuration.
+
+---
+
+## Usage Guide
+
+1. **Create or select a project** in the **Projects** tab. Each project stores conversations, specifications, and export history.
+2. **Engage with the Requirements Specialist persona** in the **Requirements Chat** tab. Provide business objectives, user roles, and product scenarios. The assistant will log messages and surface candidate user stories.
+3. **Switch to the Technical Architect persona** in the **Technical Chat** tab to capture APIs, data models, and system components with full technical depth.
+4. **Review generated specifications** in the **Validation** tab. Approve high-quality outputs, request revisions, or reject items that need more context.
+5. **Browse approved artefacts** in the **Specifications** tab. Filter by User Stories, Features, API Endpoints, Database Design, or System Architecture.
+6. **Export documentation** from the **Export** tab. Download branded HTML or AI-friendly Markdown reports that include metadata, statistics, and links back to conversations.
+7. **Manage provider settings** and rotate keys within the **Settings** tab. All changes are persisted locally so you can tailor the stack to your environment.
+
+Throughout the workflow, the application captures timestamps and associations between conversations, personas, and specifications for full traceability.
+
+---
+
+## Deployment
+
+### Local (Recommended for Development)
+
+- Follow the Quick Start steps above.
+- To run the app on a custom port, export `GRADIO_SERVER_PORT=XXXX` before launching `python app.py`.
+- Use tools like `tmux` or `systemd` if you want to keep the application running in the background.
+
+### Hugging Face Spaces
+
+Hugging Face Spaces reads the [`config.yaml`](config.yaml) manifest and pinned
+[`requirements.txt`](requirements.txt) to build and launch the application.
+
+1. Create a new **Gradio** Space and connect it to your fork of the repository.
+2. Review the metadata in `config.yaml`; update the title or colour palette if you fork the project.
+3. Set the **Space hardware** to at least the default CPU (no GPU required).
+4. In the Space **Variables** section, add any provider keys you plan to use
+   (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `XAI_API_KEY`,
+   `MOONSHOT_API_KEY`, `QWEN_API_KEY`). Spaces automatically exposes these as
+   environment variables.
+5. Optional: provide `NAEXYA_DEFAULT_PROVIDER` to specify which vendor should
+   be called first when multiple keys are present.
+6. Save the settings and rebuild the Space. Dependencies are installed from the
+   pinned versions in `requirements.txt`, and `app.py` is used as the entry
+   point.
+7. Persistent storage is available under `/data`. The application automatically
+   stores the SQLite database there when running inside a Space.
+
+> 💡 No API keys yet? Launch the Space anyway. The interface automatically
+> enters **demo mode** so you can explore the workflow using the built-in mock
+> responses, validation queue, and exports without leaving the browser.
+
+> 📘 For other hosting targets (e.g., Docker, Railway), reuse the same
+> environment variables and ensure port `7860` is exposed.
+
 ---
-title: NaexyaDocsAI
-emoji: 📚
-colorFrom: gray
-colorTo: green
-sdk: gradio
-sdk_version: 5.46.1
-app_file: app.py
-pinned: false
-license: mit
-short_description: Transform conversations into specifications.
+
+## Contributing
+
+We welcome pull requests and ideas from the community. To contribute:
+
+1. Fork the repository and create a feature branch (`git checkout -b feature/amazing-idea`).
+2. Install dependencies and run the application locally to validate your changes.
+3. Add or update documentation, including screenshots if you modify the UI.
+4. Run `python -m compileall .` (or the relevant test suite once added) to ensure there are no syntax errors.
+5. Submit a pull request describing the motivation, approach, and testing performed.
+
+Please follow the existing coding style, docstring conventions, and commit message clarity when contributing.
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## License
+
+Naexya Docs AI is released under the terms of the [MIT License](LICENSE). You are free to self-host, extend, and integrate the project in accordance with the license.
+

ai_client.py

@@ -0,0 +1,463 @@
+"""Unified AI client abstraction for Naexya Docs AI.
+
+This module centralises the integration logic for every supported AI provider,
+so the rest of the application can request completions without knowing anything
+about HTTP payload formats or authentication details.  The implementation
+favours readability and extensive inline documentation over brevity because it
+serves as both reference material and an onboarding resource for new
+contributors.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from dataclasses import dataclass
+from typing import Dict, Generator, Iterable, List, Optional, Tuple
+
+import requests
+
+from config import AI_PROVIDERS, AppConfig
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Provider configuration metadata
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ProviderConfig:
+    """Container describing the static details for a provider.
+
+    Attributes
+    ----------
+    name:
+        Human friendly label used in logs and error messages.
+    endpoint:
+        HTTPS endpoint for the chat or text generation API.
+    default_model:
+        Suggested model identifier when a caller does not provide one.
+    supports_streaming:
+        Flag documenting whether the HTTP API provides a streaming interface.
+    """
+
+    name: str
+    endpoint: str
+    default_model: str
+    supports_streaming: bool = True
+
+
+PROVIDERS: Dict[str, ProviderConfig] = {
+    # OpenAI's Chat Completions endpoint.  Authentication is handled with a
+    # Bearer token header, and the request payload is expressed as JSON.
+    "openai": ProviderConfig(
+        name="OpenAI GPT-5",
+        endpoint="https://api.openai.com/v1/chat/completions",
+        default_model="gpt-5",
+        supports_streaming=True,
+    ),
+    # Anthropic's Messages API.  This API expects a slightly different JSON
+    # schema compared to OpenAI, including an explicit "messages" array with
+    # role/content pairs.  It uses X-API-Key and Anthropic-Version headers.
+    "anthropic": ProviderConfig(
+        name="Anthropic Claude-4-Sonnet",
+        endpoint="https://api.anthropic.com/v1/messages",
+        default_model="claude-4-sonnet",
+        supports_streaming=True,
+    ),
+    # Google Gemini's Generative Language API.  It expects the content in a
+    # "contents" array that contains "parts" objects.  Authentication is
+    # performed via a query parameter instead of HTTP headers.
+    "google": ProviderConfig(
+        name="Google Gemini-2.5-Pro",
+        endpoint="https://generativelanguage.googleapis.com/v1/models/"
+        "gemini-2.5-pro:generateContent",
+        default_model="gemini-2.5-pro",
+        supports_streaming=False,
+    ),
+    # xAI's Grok models mimic the OpenAI schema but use their own endpoint and
+    # versioned Accept header.
+    "xai": ProviderConfig(
+        name="xAI Grok-4-Fast",
+        endpoint="https://api.x.ai/v1/chat/completions",
+        default_model="grok-4-fast",
+        supports_streaming=True,
+    ),
+    # Moonshot's Kimi API is also compatible with the chat completions format
+    # yet includes an "X-Api-Key" header.
+    "moonshot": ProviderConfig(
+        name="Moonshot Kimi-K2",
+        endpoint="https://api.moonshot.ai/v1/chat/completions",
+        default_model="kimi-k2",
+        supports_streaming=True,
+    ),
+    # Alibaba's Qwen DashScope endpoint accepts JSON requests with a "model"
+    # field and a "input" object.  Streaming requires a special accept header.
+    "qwen": ProviderConfig(
+        name="Qwen3-Next",
+        endpoint="https://dashscope.aliyuncs.com/api/v1/services/"
+        "aigc/text-generation/generation",
+        default_model="qwen3-next",
+        supports_streaming=True,
+    ),
+}
+
+
+# ---------------------------------------------------------------------------
+# Helper utilities
+# ---------------------------------------------------------------------------
+
+def get_provider_headers(provider: str, api_key: str) -> Dict[str, str]:
+    """Return the HTTP headers required for a specific provider.
+
+    Parameters
+    ----------
+    provider:
+        Provider identifier (e.g. ``"openai"``).  Case insensitive.
+    api_key:
+        Secret token used for authentication.  The function does *not* validate
+        the contents but will raise a :class:`ValueError` when missing.
+
+    Notes
+    -----
+    Each vendor has its own header requirements, therefore the logic is kept in
+    a dedicated helper so new providers can be added without modifying the rest
+    of the codebase.
+    """
+
+    if not api_key:
+        raise ValueError("API key is required for provider headers")
+
+    provider_key = provider.lower()
+    if provider_key == "openai":
+        return {"Authorization": f"Bearer {api_key}"}
+    if provider_key == "anthropic":
+        return {
+            "x-api-key": api_key,
+            "anthropic-version": "2023-06-01",
+            "content-type": "application/json",
+        }
+    if provider_key == "google":
+        # Google uses query string authentication, but we still provide content
+        # type for completeness.
+        return {"Content-Type": "application/json"}
+    if provider_key == "xai":
+        return {
+            "Authorization": f"Bearer {api_key}",
+            "Accept": "application/json",
+        }
+    if provider_key == "moonshot":
+        return {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
+    if provider_key == "qwen":
+        return {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        }
+
+    raise ValueError(f"Unsupported provider '{provider}'")
+
+
+def _build_payload(provider: str, model: Optional[str], messages: List[Dict[str, str]]) -> Dict[str, object]:
+    """Construct the HTTP payload matching the provider's schema."""
+
+    provider_key = provider.lower()
+    if provider_key == "openai" or provider_key == "xai" or provider_key == "moonshot":
+        return {
+            "model": model,
+            "messages": messages,
+            "stream": False,
+        }
+    if provider_key == "anthropic":
+        return {
+            "model": model,
+            "messages": [
+                {
+                    "role": message["role"],
+                    "content": message["content"],
+                }
+                for message in messages
+            ],
+            "max_tokens": 4096,
+            "stream": False,
+        }
+    if provider_key == "google":
+        # Gemini expects nested "contents" with parts containing text payloads.
+        return {
+            "model": model,
+            "contents": [
+                {
+                    "role": message["role"],
+                    "parts": [{"text": message["content"]}],
+                }
+                for message in messages
+            ],
+        }
+    if provider_key == "qwen":
+        return {
+            "model": model,
+            "input": {
+                "messages": messages,
+            },
+            "parameters": {"enable_search": False},
+        }
+
+    raise ValueError(f"Unsupported provider '{provider}'")
+
+
+# ---------------------------------------------------------------------------
+# Core API interaction helpers
+# ---------------------------------------------------------------------------
+
+def call_ai_provider(
+    provider: str,
+    model: Optional[str],
+    messages: List[Dict[str, str]],
+    api_key: str,
+    timeout: int = 60,
+) -> Dict[str, object]:
+    """Send a chat completion request to the specified provider.
+
+    The helper translates a generic ``messages`` list into the JSON body expected
+    by each API.  It returns the parsed JSON response so higher level code can
+    extract relevant fields.
+
+    Error handling is intentionally defensive: network errors, non-successful
+    HTTP responses, and JSON parsing failures are all logged with context and
+    re-raised as :class:`RuntimeError` to keep calling code consistent.
+    """
+
+    provider_key = provider.lower()
+    if provider_key not in PROVIDERS:
+        raise ValueError(f"Unsupported provider '{provider}'")
+
+    config = PROVIDERS[provider_key]
+    resolved_model = model or config.default_model
+    headers = get_provider_headers(provider_key, api_key)
+    payload = _build_payload(provider_key, resolved_model, messages)
+
+    try:
+        if provider_key == "google":
+            # Google requires the API key as a query parameter rather than header.
+            response = requests.post(
+                config.endpoint,
+                params={"key": api_key},
+                headers=headers,
+                data=json.dumps(payload),
+                timeout=timeout,
+            )
+        else:
+            response = requests.post(
+                config.endpoint,
+                headers=headers,
+                data=json.dumps(payload),
+                timeout=timeout,
+            )
+    except requests.RequestException as exc:  # pragma: no cover - network errors
+        logger.exception("Network failure when calling %s", config.name)
+        raise RuntimeError(f"Failed to reach {config.name}: {exc}") from exc
+
+    if not response.ok:
+        logger.error(
+            "Provider %s responded with status %s: %s",
+            config.name,
+            response.status_code,
+            response.text,
+        )
+        raise RuntimeError(
+            f"{config.name} returned {response.status_code}: {response.text[:200]}"
+        )
+
+    try:
+        payload = response.json()
+    except ValueError as exc:  # pragma: no cover - unexpected payloads
+        logger.exception("Invalid JSON from %s", config.name)
+        raise RuntimeError(f"Invalid JSON response from {config.name}") from exc
+
+    return payload
+
+
+def handle_streaming_response(response: Iterable[bytes]) -> Generator[str, None, None]:
+    """Convert a streaming HTTP response into decoded text chunks.
+
+    Some providers (OpenAI, Anthropic, xAI, Moonshot, Qwen) support streaming
+    tokens over an HTTP connection.  Gradio primarily expects plain text, so
+    this utility yields decoded strings one by one.  Callers can combine the
+    chunks or surface them progressively in the UI.
+    """
+
+    for chunk in response:
+        if not chunk:
+            continue
+        try:
+            decoded = chunk.decode("utf-8")
+        except UnicodeDecodeError:  # pragma: no cover - unexpected encoding
+            logger.warning("Received non UTF-8 chunk from streaming response")
+            continue
+        yield decoded
+
+
+# ---------------------------------------------------------------------------
+# Response post-processing utilities
+# ---------------------------------------------------------------------------
+
+def extract_specifications_from_response(response_text: str) -> List[Dict[str, str]]:
+    """Extract structured specification blocks from the raw model output.
+
+    The helper searches for Markdown style headings and bullet lists describing
+    requirements.  The format is intentionally permissive because different
+    models may return subtly different layouts.  The result is a list of
+    dictionaries so higher level code can serialise or store it easily.
+    """
+
+    specs: List[Dict[str, str]] = []
+    if not response_text:
+        return specs
+
+    pattern = re.compile(r"^#+\\s*(?P<title>.+)$", re.MULTILINE)
+    matches = list(pattern.finditer(response_text))
+
+    for index, match in enumerate(matches):
+        title = match.group("title").strip()
+        start = match.end()
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(response_text)
+        body = response_text[start:end].strip()
+
+        if not body:
+            continue
+
+        specs.append(
+            {
+                "title": title,
+                "content": body,
+                "status": "pending",
+            }
+        )
+
+    # Fallback: if no headings were found, treat the whole message as a single
+    # specification for manual review.
+    if not specs:
+        specs.append({"title": "Generated Specification", "content": response_text.strip(), "status": "pending"})
+
+    return specs
+
+
+# ---------------------------------------------------------------------------
+# Demo utilities
+# ---------------------------------------------------------------------------
+
+def mock_ai_response(persona_type: str, user_message: str) -> str:
+    """Return a deterministic response for demo sessions without API keys."""
+
+    persona = persona_type.lower()
+    if persona == "business":
+        return (
+            "# Business Requirement Summary\n"
+            f"Customer input: {user_message}\n\n"
+            "- Objective: Deliver clear stakeholder value.\n"
+            "- Success Criteria: Measure impact using agreed KPIs.\n"
+            "- Constraints: Respect budget and compliance limits."
+        )
+    if persona == "technical":
+        return (
+            "# Technical Solution Outline\n"
+            f"Key request: {user_message}\n\n"
+            "- Architecture: Propose modular microservices with shared auth.\n"
+            "- Integrations: Connect to existing analytics platform via REST.\n"
+            "- Risks: Validate performance under peak concurrency."
+        )
+    return (
+        "# General Response\n"
+        f"Prompt echoed: {user_message}\n\n"
+        "This persona is not defined yet, but the placeholder keeps the UI\n"
+        "functional during demos."
+    )
+
+
+class AIClient:
+    """Convenience wrapper that routes prompts to configured AI providers."""
+
+    def __init__(self, config: AppConfig):
+        self.config = config
+
+    def _resolve_provider(self) -> Tuple[str, str]:
+        """Return the provider identifier and API key to use for requests."""
+
+        preferred = self.config.default_provider.lower()
+        api_key = self.config.get_api_key(preferred)
+        if api_key:
+            return preferred, api_key
+
+        for name, credential in self.config.configured_providers().items():
+            if credential.api_key:
+                return name, credential.api_key
+
+        raise RuntimeError(
+            "No AI provider API keys are configured. Supply a key or enable demo mode."
+        )
+
+    @staticmethod
+    def _extract_text(provider: str, payload: Dict[str, object]) -> str:
+        """Normalise provider responses to a plain text string."""
+
+        try:
+            if provider in {"openai", "xai", "moonshot"}:
+                return str(payload["choices"][0]["message"]["content"]).strip()
+            if provider == "anthropic":
+                return str(payload["content"][0]["text"]).strip()
+            if provider == "google":
+                return str(payload["candidates"][0]["content"]["parts"][0]["text"]).strip()
+            if provider == "qwen":
+                output = payload.get("output") or payload.get("data") or {}
+                if isinstance(output, dict) and "text" in output:
+                    return str(output["text"]).strip()
+                if "result" in payload and isinstance(payload["result"], dict):
+                    maybe_text = payload["result"].get("output_text")
+                    if maybe_text:
+                        return str(maybe_text).strip()
+        except (IndexError, KeyError, TypeError):  # pragma: no cover - defensive
+            logger.exception("Unexpected response schema from provider %s", provider)
+
+        return str(payload)
+
+    def generate_specification(
+        self,
+        *,
+        prompt: str,
+        persona: str = "general",
+        user_message: Optional[str] = None,
+    ) -> str:
+        """Send ``prompt`` to a provider or return a deterministic demo response."""
+
+        if not isinstance(prompt, str) or not prompt.strip():
+            raise ValueError("Prompt must be a non-empty string.")
+
+        if self.config.demo_mode:
+            demo_persona = (
+                "business"
+                if persona == "requirements"
+                else "technical" if persona == "technical" else persona
+            )
+            return mock_ai_response(demo_persona, user_message or prompt)
+
+        provider, api_key = self._resolve_provider()
+        payload = call_ai_provider(
+            provider=provider,
+            model=None,
+            messages=[{"role": "user", "content": prompt.strip()}],
+            api_key=api_key,
+        )
+        return self._extract_text(provider, payload)
+
+
+__all__ = [
+    "ProviderConfig",
+    "PROVIDERS",
+    "call_ai_provider",
+    "extract_specifications_from_response",
+    "get_provider_headers",
+    "handle_streaming_response",
+    "mock_ai_response",
+    "AIClient",
+]

app.py

@@ -0,0 +1,801 @@
+"""Gradio user interface for the Naexya Docs AI application.
+
+This module assembles the full interactive experience for the project while
+remaining intentionally high-level so future contributors can plug in real
+business logic. The interface models the end-to-end workflow for capturing
+project requirements, collaborating with AI personas, validating the generated
+content, and exporting approved specifications.
+
+Key features implemented below:
+
+* Application initialization that wires together configuration, the SQLite
+  database helper, and the AI client abstraction.
+* Responsive Gradio ``Blocks`` interface composed of multiple tabs that mirror
+  the intended product workflow (projects, conversations, validation,
+  specification review, export, and settings).
+* Robust state management powered by ``gr.State`` objects so interactions remain
+  consistent across user actions and refreshes.
+* Extensive inline comments, docstrings, and structured sections to serve as a
+  living guide for engineers extending the tool.
+* Demo data helpers that allow the UI to be exercised without API keys or
+  external dependencies—ideal for automated tests and onboarding sessions.
+"""
+
+from __future__ import annotations
+
+import itertools
+import logging
+import traceback
+from dataclasses import dataclass
+from typing import Dict, Iterable, List, Optional, Tuple
+
+import gradio as gr
+
+from ai_client import AIClient
+from config import AI_PROVIDERS, AppConfig
+from database import DatabaseManager, SpecificationRecord
+from utils import format_prompt, render_export
+
+# ---------------------------------------------------------------------------
+# Application bootstrapping
+# ---------------------------------------------------------------------------
+
+# Configure logging early so helpers can emit debug information. In production
+# you might route this to structured logs or observability platforms.
+logging.basicConfig(level=logging.INFO)
+LOGGER = logging.getLogger(__name__)
+
+# Instantiate configuration, database manager, and AI client when the module is
+# imported. This ensures shared state is reused across Gradio requests.
+CONFIG: AppConfig = AppConfig.from_environment()
+DB_MANAGER = DatabaseManager(database_path=CONFIG.database_path)
+AI = AIClient(config=CONFIG)
+
+# Category definitions used throughout validation and reporting flows. The order
+# controls how sections are rendered in the Specifications tab.
+SPECIFICATION_CATEGORIES: Tuple[str, ...] = (
+    "Business Requirements",
+    "Functional Specifications",
+    "Non-Functional Requirements",
+    "Technical Architecture",
+    "Validation Criteria",
+)
+
+# Create a simple counter so each pending specification has a predictable,
+# unique identifier. ``itertools.count`` is lightweight and thread-safe for the
+# single-worker environments common when running Gradio locally.
+PENDING_ID_SEQUENCE = itertools.count(1)
+
+# Demo specification used when users enable mock data. Keeping the structure in
+# a dataclass makes the code self-documenting.
+@dataclass
+class DemoSpecification:
+    """Structure representing mock specifications bundled with the app."""
+
+    title: str
+    category: str
+    content: str
+
+
+DEMO_PROJECT_NAME = "Demo Commerce Platform"
+DEMO_SPECIFICATIONS: Tuple[DemoSpecification, ...] = (
+    DemoSpecification(
+        title="Customer Journey Overview",
+        category="Business Requirements",
+        content=(
+            "- Describe online storefront goals.\n"
+            "- Identify primary personas (shoppers, support, merchandising).\n"
+            "- Highlight success metrics such as conversion rate and AOV."
+        ),
+    ),
+    DemoSpecification(
+        title="Checkout Microservice",
+        category="Technical Architecture",
+        content=(
+            "- Python FastAPI service with PostgreSQL persistence.\n"
+            "- Integrates with payment gateway via REST webhooks.\n"
+            "- Includes observability hooks for latency and error tracking."
+        ),
+    ),
+)
+
+
+def _prepare_demo_database() -> None:
+    """Seed the SQLite database with a small demo record if empty."""
+
+    existing = list(DB_MANAGER.fetch_recent_specifications(limit=1))
+    if existing:
+        return
+
+    LOGGER.info("Seeding demo specification records")
+    for spec in DEMO_SPECIFICATIONS:
+        title = f"{spec.category}::{DEMO_PROJECT_NAME}::{spec.title}"
+        DB_MANAGER.save_specification(title=title, content=spec.content)
+
+
+# Ensure the schema exists and optionally seed demo content. The database manager
+# already creates tables on initialization; we only add demo data if none exists
+# to keep the repository self-contained for new users.
+_prepare_demo_database()
+
+
+# ---------------------------------------------------------------------------
+# Helper utilities for stateful interactions
+# ---------------------------------------------------------------------------
+
+def _ensure_project_selected(project: Optional[str]) -> None:
+    """Raise an informative error when a project has not been chosen."""
+
+    if not project:
+        raise ValueError(
+            "Please create or select a project on the Projects tab before using this feature."
+        )
+
+
+def _create_pending_entry(
+    *,
+    project: str,
+    persona: str,
+    response: str,
+    category: str,
+) -> Dict[str, str]:
+    """Compose a dictionary representing a specification awaiting validation."""
+
+    pending_id = next(PENDING_ID_SEQUENCE)
+    title = f"{project} - {persona.title()} Draft #{pending_id}"
+    return {
+        "id": str(pending_id),
+        "project": project,
+        "persona": persona,
+        "category": category,
+        "title": title,
+        "content": response,
+    }
+
+
+def _persona_prompt(persona: str, message: str) -> str:
+    """Format the user message with persona-specific guidance."""
+
+    persona_guidance = {
+        "requirements": (
+            "Act as a business analyst capturing stakeholder goals, user personas, and"
+            " measurable outcomes."
+        ),
+        "technical": (
+            "Act as a systems architect proposing services, integrations, and deployment"
+            " considerations."
+        ),
+    }
+    guidance = persona_guidance.get(persona, "Act as an assistant.")
+    return (
+        "You are collaborating on Naexya Docs AI. "
+        f"{guidance}\n\nUser message:\n{message.strip()}"
+    )
+
+
+def _record_conversation(
+    conversation_state: Dict[str, List[Tuple[str, str]]],
+    persona: str,
+    user_message: str,
+    ai_response: str,
+) -> Dict[str, List[Tuple[str, str]]]:
+    """Append conversation turns and return the mutated state copy."""
+
+    updated_history = {**conversation_state}
+    history = list(updated_history.get(persona, []))
+    history.append(("user", user_message))
+    history.append(("assistant", ai_response))
+    updated_history[persona] = history
+    return updated_history
+
+
+def _format_validation_queue(queue: Iterable[Dict[str, str]]) -> List[Tuple[str, str]]:
+    """Create friendly labels for pending specifications displayed in dropdowns."""
+
+    labels = []
+    for pending in queue:
+        label = f"#{pending['id']} · {pending['category']} · {pending['title']}"
+        labels.append((label, pending["id"]))
+    return labels
+
+
+def _group_approved_specifications(records: Iterable[SpecificationRecord]) -> Dict[str, List[str]]:
+    """Organize approved specs by category for the Specifications tab."""
+
+    grouped: Dict[str, List[str]] = {category: [] for category in SPECIFICATION_CATEGORIES}
+    for record in records:
+        if "::" in record.title:
+            category, project, name = record.title.split("::", 2)
+        else:
+            category, project, name = "Uncategorized", "Unknown Project", record.title
+        summary = f"**{project} — {name}**\n\n{record.content}".strip()
+        grouped.setdefault(category, []).append(summary)
+    return grouped
+
+
+# ---------------------------------------------------------------------------
+# Gradio callback functions (project management)
+# ---------------------------------------------------------------------------
+
+def bootstrap_application() -> Tuple[List[str], gr.Dropdown.update, str, Dict[str, List[Tuple[str, str]]], Dict[str, List[Dict[str, str]]], str]:
+    """Return initial state for the interface when the app loads."""
+
+    projects = [DEMO_PROJECT_NAME]
+    current_project = DEMO_PROJECT_NAME
+    conversation_state = {"requirements": [], "technical": []}
+    pending_state = {"queue": []}
+    if CONFIG.demo_mode:
+        status = (
+            "Loaded demo mode. Use the Projects tab to explore with mock data or"
+            " add a project once you configure API keys."
+        )
+    else:
+        status = (
+            "Ready to collaborate. Create a project or load demo data while"
+            " authenticated providers generate live specifications."
+        )
+    dropdown_update = gr.Dropdown.update(choices=projects, value=current_project)
+    return projects, dropdown_update, current_project, conversation_state, pending_state, status
+
+
+def create_project(
+    project_name: str,
+    projects: List[str],
+    current_project: Optional[str],
+) -> Tuple[List[str], gr.Dropdown.update, str, gr.Textbox.update]:
+    """Create a new project and update the selection dropdown."""
+
+    if not project_name or not project_name.strip():
+        raise ValueError("Project name cannot be empty.")
+
+    normalized_name = project_name.strip()
+    if normalized_name in projects:
+        raise ValueError(f"Project '{normalized_name}' already exists.")
+
+    updated_projects = projects + [normalized_name]
+    dropdown_update = gr.Dropdown.update(choices=updated_projects, value=normalized_name)
+    status = f"Created project '{normalized_name}' and set it as active."
+    clear_input = gr.Textbox.update(value="")
+    return updated_projects, dropdown_update, status, clear_input
+
+
+def select_project(project_name: str) -> Tuple[str, str]:
+    """Handle project selection from the dropdown."""
+
+    if not project_name:
+        raise ValueError("Select a project to continue.")
+    status = f"Active project switched to '{project_name}'."
+    return project_name, status
+
+
+def load_demo_data(
+    projects: List[str],
+    conversation_state: Dict[str, List[Tuple[str, str]]],
+    pending_state: Dict[str, List[Dict[str, str]]],
+) -> Tuple[List[str], Dict[str, List[Tuple[str, str]]], Dict[str, List[Dict[str, str]]], gr.Dropdown.update, str]:
+    """Populate application state with mock data for testing."""
+
+    demo_projects = projects if DEMO_PROJECT_NAME in projects else projects + [DEMO_PROJECT_NAME]
+
+    conversation_state = {
+        "requirements": [
+            ("user", "Outline the business goals for the ecommerce relaunch."),
+            (
+                "assistant",
+                "Generated demo summary covering revenue targets, customer journeys, and KPIs.",
+            ),
+        ],
+        "technical": [
+            ("user", "Propose the core services and integrations we need."),
+            (
+                "assistant",
+                "Demo architecture: API gateway, checkout service, event bus, analytics pipeline.",
+            ),
+        ],
+    }
+
+    queue = [
+        _create_pending_entry(
+            project=DEMO_PROJECT_NAME,
+            persona="requirements",
+            response="Demo requirements specification awaiting approval.",
+            category="Business Requirements",
+        ),
+        _create_pending_entry(
+            project=DEMO_PROJECT_NAME,
+            persona="technical",
+            response="Demo technical architecture overview pending validation.",
+            category="Technical Architecture",
+        ),
+    ]
+
+    pending_state = {"queue": queue}
+    dropdown_update = gr.Dropdown.update(choices=demo_projects, value=DEMO_PROJECT_NAME)
+    status = "Demo data loaded. Conversations and pending drafts now contain example content."
+    return demo_projects, conversation_state, pending_state, dropdown_update, status
+
+
+# ---------------------------------------------------------------------------
+# Gradio callback functions (AI conversations)
+# ---------------------------------------------------------------------------
+
+def _handle_conversation(
+    *,
+    persona: str,
+    message: str,
+    project: Optional[str],
+    conversation_state: Dict[str, List[Tuple[str, str]]],
+    pending_state: Dict[str, List[Dict[str, str]]],
+) -> Tuple[List[Tuple[str, str]], Dict[str, List[Tuple[str, str]]], Dict[str, List[Dict[str, str]]], str]:
+    """Core handler shared by both AI persona chat tabs."""
+
+    _ensure_project_selected(project)
+    if not message or not message.strip():
+        raise ValueError("Please provide a message for the AI persona.")
+
+    formatted_prompt = format_prompt(_persona_prompt(persona, message))
+
+    try:
+        ai_response = AI.generate_specification(
+            prompt=formatted_prompt,
+            persona=persona,
+            user_message=message,
+        )
+    except Exception as exc:  # pragma: no cover - defensive guard for API failures
+        LOGGER.error("AI generation failed: %s", exc)
+        LOGGER.debug("Traceback: %s", traceback.format_exc())
+        raise RuntimeError("Unable to generate a response. Check provider settings.") from exc
+
+    updated_conversation = _record_conversation(
+        conversation_state=conversation_state,
+        persona=persona,
+        user_message=message,
+        ai_response=ai_response,
+    )
+
+    category = (
+        "Business Requirements"
+        if persona == "requirements"
+        else "Technical Architecture"
+    )
+    queue = list(pending_state.get("queue", []))
+    queue.append(
+        _create_pending_entry(
+            project=project,
+            persona=persona,
+            response=ai_response,
+            category=category,
+        )
+    )
+    updated_pending = {"queue": queue}
+
+    status = "Draft added to the validation queue. Review it on the Validation tab."
+    return updated_conversation[persona], updated_conversation, updated_pending, status
+
+
+def handle_requirements_chat(
+    message: str,
+    project: Optional[str],
+    conversation_state: Dict[str, List[Tuple[str, str]]],
+    pending_state: Dict[str, List[Dict[str, str]]],
+) -> Tuple[List[Tuple[str, str]], Dict[str, List[Tuple[str, str]]], Dict[str, List[Dict[str, str]]], str]:
+    """Wrapper for the Requirements persona interaction."""
+
+    return _handle_conversation(
+        persona="requirements",
+        message=message,
+        project=project,
+        conversation_state=conversation_state,
+        pending_state=pending_state,
+    )
+
+
+def handle_technical_chat(
+    message: str,
+    project: Optional[str],
+    conversation_state: Dict[str, List[Tuple[str, str]]],
+    pending_state: Dict[str, List[Dict[str, str]]],
+) -> Tuple[List[Tuple[str, str]], Dict[str, List[Tuple[str, str]]], Dict[str, List[Dict[str, str]]], str]:
+    """Wrapper for the Technical persona interaction."""
+
+    return _handle_conversation(
+        persona="technical",
+        message=message,
+        project=project,
+        conversation_state=conversation_state,
+        pending_state=pending_state,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Gradio callback functions (validation and approvals)
+# ---------------------------------------------------------------------------
+
+def refresh_pending_specs(pending_state: Dict[str, List[Dict[str, str]]]) -> Tuple[gr.Dropdown.update, str]:
+    """Update the pending specification dropdown and display guidance."""
+
+    queue = pending_state.get("queue", [])
+    if not queue:
+        return gr.Dropdown.update(choices=[], value=None), "No drafts awaiting validation."
+
+    labels = _format_validation_queue(queue)
+    first_id = queue[0]["id"]
+    return gr.Dropdown.update(choices=labels, value=first_id), "Select a draft to review."
+
+
+def load_pending_spec(
+    spec_id: str,
+    pending_state: Dict[str, List[Dict[str, str]]],
+) -> Tuple[str, str]:
+    """Return the specification content for the selected pending draft."""
+
+    queue = pending_state.get("queue", [])
+    for pending in queue:
+        if pending["id"] == spec_id:
+            header = f"### {pending['title']}\n**Category:** {pending['category']}"
+            return header, pending["content"]
+    raise ValueError("Pending draft not found. Refresh the queue and try again.")
+
+
+def approve_specification(
+    spec_id: str,
+    project: Optional[str],
+    pending_state: Dict[str, List[Dict[str, str]]],
+) -> Tuple[Dict[str, List[Dict[str, str]]], str]:
+    """Move a pending draft into the approved specifications list."""
+
+    _ensure_project_selected(project)
+    queue = list(pending_state.get("queue", []))
+    remaining: List[Dict[str, str]] = []
+    approved_entry: Optional[Dict[str, str]] = None
+    for pending in queue:
+        if pending["id"] == spec_id:
+            approved_entry = pending
+        else:
+            remaining.append(pending)
+
+    if approved_entry is None:
+        raise ValueError("Unable to locate draft for approval. Refresh and retry.")
+
+    title = f"{approved_entry['category']}::{approved_entry['project']}::{approved_entry['title']}"
+    DB_MANAGER.save_specification(title=title, content=approved_entry["content"])
+
+    updated_state = {"queue": remaining}
+    status = f"Approved '{approved_entry['title']}'. It is now available on the Specifications tab."
+    return updated_state, status
+
+
+def reject_specification(
+    spec_id: str,
+    pending_state: Dict[str, List[Dict[str, str]]],
+) -> Tuple[Dict[str, List[Dict[str, str]]], str]:
+    """Remove a pending draft without saving it to the database."""
+
+    queue = list(pending_state.get("queue", []))
+    remaining: List[Dict[str, str]] = []
+    removed: Optional[Dict[str, str]] = None
+    for pending in queue:
+        if pending["id"] == spec_id:
+            removed = pending
+        else:
+            remaining.append(pending)
+
+    if removed is None:
+        raise ValueError("Draft not found. Refresh the queue and retry.")
+
+    updated_state = {"queue": remaining}
+    status = f"Rejected '{removed['title']}'. It has been removed from the queue."
+    return updated_state, status
+
+
+# ---------------------------------------------------------------------------
+# Gradio callback functions (specifications, export, and settings)
+# ---------------------------------------------------------------------------
+
+def refresh_specifications_view() -> List[str]:
+    """Retrieve approved specifications and format markdown for each category."""
+
+    records = DB_MANAGER.fetch_recent_specifications(limit=200)
+    grouped = _group_approved_specifications(records)
+    rendered_sections: List[str] = []
+    for category in SPECIFICATION_CATEGORIES:
+        entries = grouped.get(category, [])
+        if entries:
+            rendered_sections.append("\n\n---\n\n".join(entries))
+        else:
+            rendered_sections.append("*No approved specifications yet.*")
+    return rendered_sections
+
+
+def export_specification(
+    spec_id: str,
+    export_format: str,
+) -> Tuple[str, str]:
+    """Render the selected specification using the HTML or Markdown template."""
+
+    if not spec_id:
+        raise ValueError("Select a specification to export.")
+
+    records = list(DB_MANAGER.fetch_recent_specifications(limit=200))
+    selected: Optional[SpecificationRecord] = None
+    for record in records:
+        if record.id == int(spec_id):
+            selected = record
+            break
+
+    if selected is None:
+        raise ValueError("Select a specification to export.")
+
+    context = {"title": selected.title, "content": selected.content}
+    template = "export_html.html" if export_format == "HTML" else "export_markdown.md"
+    rendered = render_export(template_name=template, context=context)
+    notice = f"Rendered {export_format} export for specification #{selected.id}."
+    return rendered, notice
+
+
+def list_exportable_specs() -> gr.Dropdown.update:
+    """Populate the export dropdown with approved specifications."""
+
+    records = DB_MANAGER.fetch_recent_specifications(limit=200)
+    options = [(record.title, str(record.id)) for record in records]
+    return gr.Dropdown.update(choices=options, value=(options[0][1] if options else None))
+
+
+def summarize_settings() -> str:
+    """Provide a user-friendly summary of configured providers."""
+
+    lines: List[str] = []
+    for key, credential in CONFIG.providers.items():
+        display = AI_PROVIDERS.get(key, {}).get("display_name", key.title())
+        lines.append(
+            f"- **{display}:** {'Configured' if credential.api_key else 'Not configured'}"
+        )
+
+    if CONFIG.demo_mode:
+        lines.append(
+            "\nDemo mode is active because no API keys were detected."
+            " You can explore the interface with deterministic mock responses."
+        )
+    else:
+        lines.append(
+            "\nAt least one provider key is configured. Update `NAEXYA_DEFAULT_PROVIDER`"
+            " to control which service is used first."
+        )
+
+    if CONFIG.space_id:
+        lines.append(
+            "Running inside a Hugging Face Space. Persistent data is stored under `/data`."
+        )
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Interface construction
+# ---------------------------------------------------------------------------
+
+RESPONSIVE_CSS = """
+@media (max-width: 768px) {
+  .two-column {flex-direction: column !important;}
+}
+"""
+
+
+def build_interface() -> gr.Blocks:
+    """Create the Gradio Blocks interface with all workflow tabs."""
+
+    with gr.Blocks(title="Naexya Docs AI", css=RESPONSIVE_CSS) as demo:
+        gr.Markdown(
+            """
+            # Naexya Docs AI
+            Collaborate with AI personas to capture, validate, and export rich project specifications.
+            Use the tabs below to move sequentially from project setup through final export.
+            """
+        )
+
+        # Shared state stores the active project, persona chat histories, pending drafts,
+        # and the full list of projects available in the dropdown.
+        project_list_state = gr.State([DEMO_PROJECT_NAME])
+        current_project_state = gr.State(DEMO_PROJECT_NAME)
+        conversation_state = gr.State({"requirements": [], "technical": []})
+        pending_specs_state = gr.State({"queue": []})
+
+        # ------------------------------------------------------------------
+        # Projects tab: manage project lifecycle and demo content
+        # ------------------------------------------------------------------
+        with gr.TabItem("Projects"):
+            gr.Markdown(
+                """Use this tab to create new projects, switch context, or load demo data."""
+            )
+            with gr.Row(elem_classes="two-column"):
+                with gr.Column():
+                    project_name_input = gr.Textbox(label="New Project Name", placeholder="e.g. Mobile Banking App")
+                    create_project_button = gr.Button("Create Project", variant="primary")
+                with gr.Column():
+                    project_dropdown = gr.Dropdown(label="Active Project", choices=[DEMO_PROJECT_NAME], value=DEMO_PROJECT_NAME)
+                    select_project_button = gr.Button("Set Active Project", variant="secondary")
+            demo_data_button = gr.Button("Load Demo Data", variant="secondary")
+            project_status = gr.Markdown()
+
+        # ------------------------------------------------------------------
+        # Requirements Chat tab
+        # ------------------------------------------------------------------
+        with gr.TabItem("Requirements Chat"):
+            gr.Markdown(
+                """
+                Chat with a business analyst persona to capture stakeholder needs, success metrics,
+                and product scope. Each response is added to the validation queue.
+                """
+            )
+            requirements_chat = gr.Chatbot(height=350)
+            with gr.Row(elem_classes="two-column"):
+                requirements_input = gr.Textbox(label="Message", placeholder="Describe goals, constraints, and personas...", lines=3)
+                requirements_submit = gr.Button("Send", variant="primary")
+            requirements_status = gr.Markdown()
+
+        # ------------------------------------------------------------------
+        # Technical Chat tab
+        # ------------------------------------------------------------------
+        with gr.TabItem("Technical Chat"):
+            gr.Markdown(
+                """
+                Collaborate with a systems architect persona on integrations, services, and deployment
+                considerations. Drafts also flow into the validation queue for review.
+                """
+            )
+            technical_chat = gr.Chatbot(height=350)
+            with gr.Row(elem_classes="two-column"):
+                technical_input = gr.Textbox(label="Message", placeholder="Ask for architecture proposals, sequencing, or risks...", lines=3)
+                technical_submit = gr.Button("Send", variant="primary")
+            technical_status = gr.Markdown()
+
+        # ------------------------------------------------------------------
+        # Validation tab
+        # ------------------------------------------------------------------
+        with gr.TabItem("Validation"):
+            gr.Markdown("""Review drafts generated by AI personas and approve or reject them.""")
+            refresh_pending_button = gr.Button("Refresh Pending Drafts", variant="secondary")
+            pending_dropdown = gr.Dropdown(label="Pending Drafts", choices=[], interactive=True)
+            pending_header = gr.Markdown()
+            pending_content = gr.Markdown()
+            with gr.Row():
+                approve_button = gr.Button("Approve", variant="primary")
+                reject_button = gr.Button("Reject", variant="stop")
+            validation_status = gr.Markdown()
+
+        # ------------------------------------------------------------------
+        # Specifications tab
+        # ------------------------------------------------------------------
+        with gr.TabItem("Specifications"):
+            gr.Markdown("""Browse approved specifications grouped by category.""")
+            refresh_specs_button = gr.Button("Refresh View", variant="secondary")
+            category_outputs = []
+            for category in SPECIFICATION_CATEGORIES:
+                with gr.Accordion(category, open=False):
+                    markdown = gr.Markdown("*No approved specifications yet.*")
+                    category_outputs.append(markdown)
+
+        # ------------------------------------------------------------------
+        # Export tab
+        # ------------------------------------------------------------------
+        with gr.TabItem("Export"):
+            gr.Markdown("""Select an approved specification and render it using the export templates.""")
+            export_refresh_button = gr.Button("Refresh Approved List", variant="secondary")
+            export_dropdown = gr.Dropdown(label="Approved Specifications", choices=[])
+            export_format_radio = gr.Radio(["Markdown", "HTML"], value="Markdown", label="Export Format")
+            export_button = gr.Button("Render Export", variant="primary")
+            export_preview = gr.Code(label="Export Preview", language="markdown")
+            export_status = gr.Markdown()
+
+        # ------------------------------------------------------------------
+        # Settings tab
+        # ------------------------------------------------------------------
+        with gr.TabItem("Settings"):
+            gr.Markdown(
+                """
+                Configure AI providers by supplying API keys in your environment. Use this summary to
+                verify which providers are currently active. Demo data remains available even without keys.
+                """
+            )
+            settings_summary = gr.Markdown(summarize_settings())
+            gr.Markdown(
+                """Refer to `.env.example` for the list of supported providers and required environment variables."""
+            )
+
+        # ------------------------------------------------------------------
+        # Wiring callbacks to UI interactions
+        # ------------------------------------------------------------------
+
+        # Application bootstrap when the interface loads.
+        demo.load(
+            fn=bootstrap_application,
+            inputs=None,
+            outputs=[project_list_state, project_dropdown, current_project_state, conversation_state, pending_specs_state, project_status],
+        )
+
+        # Project management actions.
+        create_project_button.click(
+            fn=create_project,
+            inputs=[project_name_input, project_list_state, current_project_state],
+            outputs=[project_list_state, project_dropdown, project_status, project_name_input],
+        )
+
+        select_project_button.click(
+            fn=select_project,
+            inputs=project_dropdown,
+            outputs=[current_project_state, project_status],
+        )
+
+        demo_data_button.click(
+            fn=load_demo_data,
+            inputs=[project_list_state, conversation_state, pending_specs_state],
+            outputs=[project_list_state, conversation_state, pending_specs_state, project_dropdown, project_status],
+        )
+
+        # Requirements persona interactions.
+        requirements_submit.click(
+            fn=handle_requirements_chat,
+            inputs=[requirements_input, current_project_state, conversation_state, pending_specs_state],
+            outputs=[requirements_chat, conversation_state, pending_specs_state, requirements_status],
+        )
+
+        # Technical persona interactions.
+        technical_submit.click(
+            fn=handle_technical_chat,
+            inputs=[technical_input, current_project_state, conversation_state, pending_specs_state],
+            outputs=[technical_chat, conversation_state, pending_specs_state, technical_status],
+        )
+
+        # Validation workflows.
+        refresh_pending_button.click(
+            fn=refresh_pending_specs,
+            inputs=pending_specs_state,
+            outputs=[pending_dropdown, validation_status],
+        )
+        pending_dropdown.change(
+            fn=load_pending_spec,
+            inputs=[pending_dropdown, pending_specs_state],
+            outputs=[pending_header, pending_content],
+        )
+        approve_button.click(
+            fn=approve_specification,
+            inputs=[pending_dropdown, current_project_state, pending_specs_state],
+            outputs=[pending_specs_state, validation_status],
+        )
+        reject_button.click(
+            fn=reject_specification,
+            inputs=[pending_dropdown, pending_specs_state],
+            outputs=[pending_specs_state, validation_status],
+        )
+
+        # Approved specifications browsing.
+        refresh_specs_button.click(
+            fn=refresh_specifications_view,
+            inputs=None,
+            outputs=category_outputs,
+        )
+
+        # Export workflow.
+        export_refresh_button.click(
+            fn=list_exportable_specs,
+            inputs=None,
+            outputs=export_dropdown,
+        )
+        export_button.click(
+            fn=export_specification,
+            inputs=[export_dropdown, export_format_radio],
+            outputs=[export_preview, export_status],
+        )
+
+    return demo
+
+
+def main() -> None:
+    """Launch the Gradio development server."""
+
+    interface = build_interface()
+    interface.launch()
+
+
+if __name__ == "__main__":
+    main()

config.py

@@ -0,0 +1,397 @@
+"""Centralized configuration for the Naexya Docs AI application.
+
+This module defines provider metadata, persona prompt templates, specification
+categories, and export rendering configuration in a single location. Keeping
+these values together makes it easier to maintain consistent behaviour across
+modules such as ``ai_client.py`` and ``app.py``.
+
+The dictionaries below are intentionally verbose and heavily commented so that
+future contributors can understand every field without cross-referencing API
+documentation.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+try:  # Loading .env files is optional but convenient for local development.
+    from dotenv import load_dotenv
+except ImportError:  # pragma: no cover - dependency may be missing in some envs.
+    def load_dotenv(*_args: object, **_kwargs: object) -> bool:
+        """Fallback stub when python-dotenv is not installed."""
+
+        return False
+
+# ---------------------------------------------------------------------------
+# AI Provider configuration
+# ---------------------------------------------------------------------------
+# ``AI_PROVIDERS`` captures the details required to interact with each
+# third-party large language model. Each entry explains the authentication
+# header, supported models, and default parameter choices that the application
+# should use. Additional providers can be added by following the same schema.
+AI_PROVIDERS: Dict[str, Dict[str, Any]] = {
+    "openai": {
+        "display_name": "OpenAI",
+        # Base endpoint for Chat Completions. Individual modules append
+        # provider-specific paths as needed.
+        "base_url": "https://api.openai.com/v1",
+        "chat_endpoint": "https://api.openai.com/v1/chat/completions",
+        "default_model": "gpt-5",
+        "available_models": ["gpt-5"],
+        # The provider requires a Bearer token with the ``Authorization`` header.
+        "headers": {
+            "Authorization": "Bearer {api_key}",
+            "Content-Type": "application/json",
+        },
+        # Conservative defaults to balance quality with latency and cost.
+        "default_params": {"temperature": 0.7, "max_tokens": 2048},
+        # Basic rate-limit guidance for UI messaging and back-off strategies.
+        "rate_limits": {
+            "requests_per_minute": 500,
+            "tokens_per_minute": 600000,
+        },
+    },
+    "anthropic": {
+        "display_name": "Anthropic",
+        "base_url": "https://api.anthropic.com/v1",
+        "chat_endpoint": "https://api.anthropic.com/v1/messages",
+        "default_model": "claude-4-sonnet",
+        "available_models": ["claude-4-sonnet"],
+        # Anthropic expects both ``x-api-key`` and ``anthropic-version`` headers.
+        "headers": {
+            "x-api-key": "{api_key}",
+            "anthropic-version": "2023-06-01",
+            "Content-Type": "application/json",
+        },
+        "default_params": {"temperature": 0.7, "max_tokens": 2048},
+        "rate_limits": {
+            "requests_per_minute": 400,
+            "tokens_per_minute": 480000,
+        },
+    },
+    "google": {
+        "display_name": "Google",
+        "base_url": "https://generativelanguage.googleapis.com/v1",
+        "chat_endpoint": "https://generativelanguage.googleapis.com/v1/models/gemini-2.5-pro:generateContent",
+        "default_model": "gemini-2.5-pro",
+        "available_models": ["gemini-2.5-pro"],
+        # Gemini uses a query parameter for the API key; headers remain JSON.
+        "headers": {"Content-Type": "application/json"},
+        "default_params": {"temperature": 0.7, "max_output_tokens": 2048},
+        "rate_limits": {
+            "requests_per_minute": 300,
+            "tokens_per_minute": 360000,
+        },
+    },
+    "xai": {
+        "display_name": "xAI",
+        "base_url": "https://api.x.ai/v1",
+        "chat_endpoint": "https://api.x.ai/v1/chat/completions",
+        "default_model": "grok-4-fast",
+        "available_models": ["grok-4-fast"],
+        "headers": {
+            "Authorization": "Bearer {api_key}",
+            "Content-Type": "application/json",
+        },
+        "default_params": {"temperature": 0.7, "max_tokens": 2048},
+        "rate_limits": {
+            "requests_per_minute": 200,
+            "tokens_per_minute": 240000,
+        },
+    },
+    "moonshot": {
+        "display_name": "Moonshot",
+        "base_url": "https://api.moonshot.ai/v1",
+        "chat_endpoint": "https://api.moonshot.ai/v1/chat/completions",
+        "default_model": "kimi-k2",
+        "available_models": ["kimi-k2"],
+        "headers": {
+            "Authorization": "Bearer {api_key}",
+            "Content-Type": "application/json",
+        },
+        "default_params": {"temperature": 0.7, "max_tokens": 2048},
+        "rate_limits": {
+            "requests_per_minute": 150,
+            "tokens_per_minute": 180000,
+        },
+    },
+    "qwen": {
+        "display_name": "Qwen",
+        "base_url": "https://dashscope.aliyuncs.com/api/v1",
+        "chat_endpoint": "https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation",
+        "default_model": "qwen3-next",
+        "available_models": ["qwen3-next"],
+        "headers": {
+            "Authorization": "Bearer {api_key}",
+            "Content-Type": "application/json",
+        },
+        "default_params": {"temperature": 0.7, "max_tokens": 2048},
+        "rate_limits": {
+            "requests_per_minute": 250,
+            "tokens_per_minute": 300000,
+        },
+    },
+}
+
+# ---------------------------------------------------------------------------
+# Persona configuration
+# ---------------------------------------------------------------------------
+# Personas determine how AI assistants respond to users. Providing rich,
+# descriptive prompts ensures that conversations remain on-topic and that the
+# extracted specifications are actionable.
+AI_PERSONAS: Dict[str, Dict[str, str]] = {
+    "requirements_specialist": {
+        "display_name": "Requirements Specialist",
+        "prompt": (
+            "You are an expert business analyst specializing in gathering and "
+            "documenting software requirements. Focus on user stories, business "
+            "features, workflows, and functional requirements. Always ask "
+            "clarifying questions and provide structured output."
+        ),
+    },
+    "technical_architect": {
+        "display_name": "Technical Architect",
+        "prompt": (
+            "You are a senior technical architect specializing in system design "
+            "and implementation. Focus on API specifications, database schemas, "
+            "system architecture, and technical implementation details. Provide "
+            "detailed technical specifications."
+        ),
+    },
+}
+
+# ---------------------------------------------------------------------------
+# Specification taxonomy
+# ---------------------------------------------------------------------------
+# ``SPECIFICATION_TYPES`` controls the categories displayed in the UI when
+# reviewing and exporting specifications.
+SPECIFICATION_TYPES = [
+    "User Stories",
+    "Features",
+    "API Endpoints",
+    "Database Design",
+    "System Architecture",
+]
+
+# ---------------------------------------------------------------------------
+# Export template configuration
+# ---------------------------------------------------------------------------
+# Each export format references template files stored under ``templates/``. The
+# metadata here describes how those templates should be used by the export
+# helpers in ``utils.py`` or ``app.py``.
+EXPORT_TEMPLATES: Dict[str, Dict[str, str]] = {
+    "html": {
+        "path": "templates/export_html.html",
+        "content_type": "text/html",
+        "description": "Rich HTML report suitable for sharing with stakeholders.",
+    },
+    "markdown": {
+        "path": "templates/export_markdown.md",
+        "content_type": "text/markdown",
+        "description": "Lightweight Markdown export for version control or wikis.",
+    },
+}
+
+# ---------------------------------------------------------------------------
+# Application configuration dataclasses
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ProviderCredential:
+    """Runtime view of provider configuration resolved from the environment."""
+
+    provider: str
+    env_var: str
+    api_key: Optional[str] = None
+
+    @property
+    def display_name(self) -> str:
+        """Return the human-friendly name defined in ``AI_PROVIDERS``."""
+
+        provider_meta = AI_PROVIDERS.get(self.provider, {})
+        return provider_meta.get("display_name", self.provider.title())
+
+
+@dataclass
+class AppConfig:
+    """Container holding runtime configuration for the Gradio interface."""
+
+    database_path: Path
+    providers: Dict[str, ProviderCredential] = field(default_factory=dict)
+    default_provider: str = "openai"
+    demo_mode: bool = False
+    space_id: Optional[str] = None
+
+    @classmethod
+    def from_environment(cls) -> "AppConfig":
+        """Build an :class:`AppConfig` instance using environment variables."""
+
+        load_dotenv()
+        validate_configuration()
+
+        env = os.environ
+        is_spaces = any(env.get(var) for var in ("SPACE_ID", "HF_SPACE_ID", "HF_HOME"))
+        data_dir = Path(
+            env.get("NAEXYA_DATA_DIR")
+            or ("/data" if is_spaces else Path(__file__).resolve().parent)
+        )
+        data_dir.mkdir(parents=True, exist_ok=True)
+        database_path = (data_dir / env.get("NAEXYA_DB_FILENAME", "naexya_docs_ai.db")).resolve()
+
+        provider_env_map = {
+            "openai": "OPENAI_API_KEY",
+            "anthropic": "ANTHROPIC_API_KEY",
+            "google": "GOOGLE_API_KEY",
+            "xai": "XAI_API_KEY",
+            "moonshot": "MOONSHOT_API_KEY",
+            "qwen": "QWEN_API_KEY",
+        }
+
+        providers = {
+            name: ProviderCredential(
+                provider=name,
+                env_var=env_var,
+                api_key=env.get(env_var) or None,
+            )
+            for name, env_var in provider_env_map.items()
+        }
+
+        # Choose a sensible default provider, preferring explicit environment configuration.
+        configured = [key for key, cred in providers.items() if cred.api_key]
+        requested_default = (env.get("NAEXYA_DEFAULT_PROVIDER") or "openai").lower()
+        if requested_default not in providers:
+            requested_default = "openai"
+        default_provider = requested_default if (configured and requested_default in configured) else (configured[0] if configured else "openai")
+
+        demo_mode = not bool(configured)
+
+        return cls(
+            database_path=database_path,
+            providers=providers,
+            default_provider=default_provider,
+            demo_mode=demo_mode,
+            space_id=env.get("SPACE_ID") or env.get("HF_SPACE_ID"),
+        )
+
+    def get_api_key(self, provider: str) -> Optional[str]:
+        """Retrieve the configured API key for ``provider`` if available."""
+
+        credential = self.providers.get(provider.lower())
+        return credential.api_key if credential else None
+
+    def configured_providers(self) -> Dict[str, ProviderCredential]:
+        """Return only the providers that currently have API keys configured."""
+
+        return {name: cred for name, cred in self.providers.items() if cred.api_key}
+
+
+# ---------------------------------------------------------------------------
+# Validation utilities
+# ---------------------------------------------------------------------------
+# The functions below provide quick sanity checks that configuration dictionaries
+# contain the expected fields. They raise ``ValueError`` with descriptive
+# messages so callers can fail fast during application start-up.
+
+def validate_provider_config(provider_key: str) -> None:
+    """Validate a single provider configuration entry.
+
+    Args:
+        provider_key: The dictionary key identifying the provider (e.g. ``"openai"``).
+
+    Raises:
+        ValueError: If required fields are missing or improperly formatted.
+    """
+
+    config = AI_PROVIDERS.get(provider_key)
+    if config is None:
+        raise ValueError(f"Provider '{provider_key}' is not defined in AI_PROVIDERS.")
+
+    required_fields = [
+        "display_name",
+        "base_url",
+        "chat_endpoint",
+        "default_model",
+        "headers",
+        "default_params",
+        "rate_limits",
+    ]
+    missing = [field for field in required_fields if field not in config]
+    if missing:
+        raise ValueError(
+            f"Provider '{provider_key}' is missing required fields: {', '.join(missing)}"
+        )
+
+    if "Authorization" in config["headers"] and "{api_key}" not in config["headers"]["Authorization"]:
+        raise ValueError(
+            f"Provider '{provider_key}' Authorization header must include '{{api_key}}' placeholder."
+        )
+
+
+def validate_all_providers() -> None:
+    """Validate every provider configuration entry."""
+
+    for provider_key in AI_PROVIDERS:
+        validate_provider_config(provider_key)
+
+
+def validate_personas() -> None:
+    """Ensure persona definitions include prompts for consistent behaviour."""
+
+    for key, persona in AI_PERSONAS.items():
+        if "prompt" not in persona or not persona["prompt"].strip():
+            raise ValueError(f"Persona '{key}' must include a non-empty prompt.")
+
+
+def validate_specification_types() -> None:
+    """Verify specification types are unique and non-empty."""
+
+    if not SPECIFICATION_TYPES:
+        raise ValueError("SPECIFICATION_TYPES must contain at least one entry.")
+
+    normalized = [spec.strip() for spec in SPECIFICATION_TYPES if spec.strip()]
+    if len(normalized) != len(SPECIFICATION_TYPES):
+        raise ValueError("SPECIFICATION_TYPES must not contain blank values.")
+
+    if len(set(normalized)) != len(normalized):
+        raise ValueError("SPECIFICATION_TYPES entries must be unique.")
+
+
+def validate_export_templates() -> None:
+    """Confirm export template metadata includes expected fields."""
+
+    required_fields = {"path", "content_type", "description"}
+    for key, template in EXPORT_TEMPLATES.items():
+        missing = required_fields - template.keys()
+        if missing:
+            raise ValueError(
+                f"Export template '{key}' is missing fields: {', '.join(sorted(missing))}"
+            )
+
+
+def validate_configuration() -> None:
+    """Run all configuration validators.
+
+    This helper is convenient during application start-up to ensure environment
+    configuration issues are detected early rather than failing deep inside the
+    request cycle.
+    """
+
+    validate_all_providers()
+    validate_personas()
+    validate_specification_types()
+    validate_export_templates()
+
+
+__all__ = [
+    "AI_PROVIDERS",
+    "AI_PERSONAS",
+    "SPECIFICATION_TYPES",
+    "EXPORT_TEMPLATES",
+    "ProviderCredential",
+    "AppConfig",
+    "validate_configuration",
+]

config.yaml

@@ -0,0 +1,9 @@
+title: Naexya Docs AI
+emoji: "📋"
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 4.0.0
+app_file: app.py
+pinned: false
+license: mit

database.py

@@ -0,0 +1,589 @@
+"""Database layer for Naexya Docs AI.
+
+This module centralises all SQLite interactions used by the application. By
+keeping the SQL logic in one place the rest of the codebase can focus on the
+business workflow while delegating persistence concerns here.  Each function is
+carefully documented so future contributors understand not only *what* the
+function does but *why* the design decisions were made.
+
+The helper functions below follow a handful of guiding principles:
+
+* **Single connection helper** – ``_get_connection`` ensures every call uses
+  the same connection configuration and enables ``sqlite3.Row`` mapping for
+  ergonomic dictionary-style access.
+* **Explicit transactions** – ``with`` blocks are used to guarantee commits and
+  to automatically close connections regardless of success or failure.
+* **Robust error handling** – problems are logged with contextual information
+  before being re-raised, giving the caller an opportunity to surface helpful
+  feedback in the UI while still capturing the original stack trace.
+* **Comprehensive comments** – inline notes explain the schema, relationships,
+  and reasoning so the file doubles as lightweight documentation.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional
+
+# ---------------------------------------------------------------------------
+# Module-level configuration
+# ---------------------------------------------------------------------------
+
+# Resolve the database file relative to this module.  Placing the database in
+# the repository root keeps the demo self-contained while allowing advanced
+# users to supply a custom path when embedding the library elsewhere.
+DATABASE_PATH = Path(__file__).resolve().parent / "naexya_docs_ai.db"
+
+# Configure a module-specific logger so calling code can hook into the
+# application's logging setup.  ``getLogger(__name__)`` ensures messages are
+# namespaced to ``database`` making them easy to filter.
+LOGGER = logging.getLogger(__name__)
+
+
+def _get_connection(db_path: Optional[Path] = None) -> sqlite3.Connection:
+    """Create a SQLite connection with row access configured.
+
+    Args:
+        db_path: Optional custom database path.  When ``None`` the default
+            ``DATABASE_PATH`` constant is used.
+
+    Returns:
+        A ``sqlite3.Connection`` instance with ``row_factory`` set to
+        ``sqlite3.Row`` so query results behave like dictionaries.
+    """
+
+    connection = sqlite3.connect(db_path or DATABASE_PATH)
+    connection.row_factory = sqlite3.Row
+    return connection
+
+
+# ---------------------------------------------------------------------------
+# Schema management
+# ---------------------------------------------------------------------------
+
+def init_database(db_path: Optional[Path] = None) -> None:
+    """Create all required tables if they do not already exist.
+
+    The application stores projects, conversations, chat messages, and
+    extracted specifications.  ``init_database`` is idempotent; running it
+    multiple times simply ensures the schema remains available without wiping
+    existing data.
+    """
+
+    LOGGER.debug("Initialising SQLite schema")
+    try:
+        with _get_connection(db_path) as conn:
+            cursor = conn.cursor()
+
+            # ``projects`` table stores the high-level workspace definition
+            # containing a human-friendly name and optional description.
+            cursor.execute(
+                """
+                CREATE TABLE IF NOT EXISTS projects (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    name TEXT NOT NULL UNIQUE,
+                    description TEXT,
+                    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+                )
+                """
+            )
+
+            # ``conversations`` capture separate chat threads for each persona
+            # (requirements, technical, etc.) and link back to the owning
+            # project.  ``is_locked`` helps us prevent further edits once a
+            # conversation has been validated.
+            cursor.execute(
+                """
+                CREATE TABLE IF NOT EXISTS conversations (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    project_id INTEGER NOT NULL,
+                    persona_type TEXT NOT NULL,
+                    is_locked INTEGER DEFAULT 0,
+                    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+                    FOREIGN KEY (project_id) REFERENCES projects(id)
+                )
+                """
+            )
+
+            # ``messages`` belong to a conversation and capture the actual
+            # dialog history.  ``role`` mirrors the familiar OpenAI convention
+            # of ``user`` and ``assistant`` to keep the data structure flexible
+            # if additional participants are ever introduced.
+            cursor.execute(
+                """
+                CREATE TABLE IF NOT EXISTS messages (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    conversation_id INTEGER NOT NULL,
+                    role TEXT NOT NULL,
+                    content TEXT NOT NULL,
+                    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
+                    FOREIGN KEY (conversation_id) REFERENCES conversations(id)
+                )
+                """
+            )
+
+            # ``specifications`` house the structured outputs created by the
+            # AI personas.  ``status`` tracks whether an item is pending
+            # validation or has been approved by a human reviewer.
+            cursor.execute(
+                """
+                CREATE TABLE IF NOT EXISTS specifications (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    project_id INTEGER NOT NULL,
+                    conversation_id INTEGER,
+                    spec_type TEXT NOT NULL,
+                    title TEXT NOT NULL,
+                    content TEXT NOT NULL,
+                    status TEXT DEFAULT 'pending',
+                    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+                    FOREIGN KEY (project_id) REFERENCES projects(id),
+                    FOREIGN KEY (conversation_id) REFERENCES conversations(id)
+                )
+                """
+            )
+
+            # ``approved_specs`` is a lightweight table dedicated to storing
+            # validated specification summaries used by the Gradio interface.
+            # Keeping a separate table avoids interfering with the richer
+            # workflow tables above while providing a simple history for
+            # export operations and demo content.
+            cursor.execute(
+                """
+                CREATE TABLE IF NOT EXISTS approved_specs (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    title TEXT NOT NULL,
+                    content TEXT NOT NULL,
+                    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+                )
+                """
+            )
+
+            conn.commit()
+    except sqlite3.DatabaseError as error:
+        LOGGER.exception("Database initialisation failed: %s", error)
+        raise
+
+
+# ---------------------------------------------------------------------------
+# Project management helpers
+# ---------------------------------------------------------------------------
+
+def create_project(name: str, description: str = "", db_path: Optional[Path] = None) -> int:
+    """Insert a new project row and return its generated ID."""
+
+    LOGGER.info("Creating project: %s", name)
+    try:
+        with _get_connection(db_path) as conn:
+            cursor = conn.execute(
+                "INSERT INTO projects (name, description) VALUES (?, ?)",
+                (name, description),
+            )
+            conn.commit()
+            project_id = cursor.lastrowid
+            LOGGER.debug("Created project %s with id %s", name, project_id)
+            return project_id
+    except sqlite3.IntegrityError as error:
+        # ``IntegrityError`` handles duplicate names and other constraint
+        # violations.  Re-raising with context helps the UI provide clear
+        # feedback, for example when a user accidentally creates a duplicate
+        # project.
+        LOGGER.exception("Failed to create project '%s': %s", name, error)
+        raise
+
+
+def get_projects(db_path: Optional[Path] = None) -> List[Dict[str, str]]:
+    """Return all projects ordered by most recent first."""
+
+    LOGGER.debug("Fetching project list")
+    try:
+        with _get_connection(db_path) as conn:
+            rows = conn.execute(
+                "SELECT id, name, description, created_at FROM projects ORDER BY created_at DESC"
+            ).fetchall()
+            return [dict(row) for row in rows]
+    except sqlite3.DatabaseError as error:
+        LOGGER.exception("Failed to fetch projects: %s", error)
+        raise
+
+
+# ---------------------------------------------------------------------------
+# Conversation helpers
+# ---------------------------------------------------------------------------
+
+def create_conversation(
+    project_id: int,
+    persona_type: str,
+    db_path: Optional[Path] = None,
+) -> int:
+    """Start a new conversation for the supplied project and persona."""
+
+    LOGGER.info("Starting %s conversation for project %s", persona_type, project_id)
+    try:
+        with _get_connection(db_path) as conn:
+            cursor = conn.execute(
+                "INSERT INTO conversations (project_id, persona_type) VALUES (?, ?)",
+                (project_id, persona_type),
+            )
+            conn.commit()
+            conversation_id = cursor.lastrowid
+            LOGGER.debug("Conversation %s created", conversation_id)
+            return conversation_id
+    except sqlite3.DatabaseError as error:
+        LOGGER.exception(
+            "Failed to create conversation for project %s (%s): %s",
+            project_id,
+            persona_type,
+            error,
+        )
+        raise
+
+
+def add_message(
+    conversation_id: int,
+    role: str,
+    content: str,
+    db_path: Optional[Path] = None,
+) -> int:
+    """Persist an individual chat message belonging to a conversation."""
+
+    LOGGER.debug("Adding %s message to conversation %s", role, conversation_id)
+    try:
+        with _get_connection(db_path) as conn:
+            cursor = conn.execute(
+                "INSERT INTO messages (conversation_id, role, content) VALUES (?, ?, ?)",
+                (conversation_id, role, content),
+            )
+            conn.commit()
+            message_id = cursor.lastrowid
+            LOGGER.debug("Stored message %s", message_id)
+            return message_id
+    except sqlite3.DatabaseError as error:
+        LOGGER.exception(
+            "Failed to add message to conversation %s: %s", conversation_id, error
+        )
+        raise
+
+
+def lock_conversation(conversation_id: int, db_path: Optional[Path] = None) -> None:
+    """Mark a conversation as locked to prevent further editing."""
+
+    LOGGER.info("Locking conversation %s", conversation_id)
+    try:
+        with _get_connection(db_path) as conn:
+            conn.execute(
+                "UPDATE conversations SET is_locked = 1 WHERE id = ?",
+                (conversation_id,),
+            )
+            conn.commit()
+    except sqlite3.DatabaseError as error:
+        LOGGER.exception("Failed to lock conversation %s: %s", conversation_id, error)
+        raise
+
+
+# ---------------------------------------------------------------------------
+# Specification helpers
+# ---------------------------------------------------------------------------
+
+def create_specification(
+    project_id: int,
+    conversation_id: Optional[int],
+    spec_type: str,
+    title: str,
+    content: str,
+    db_path: Optional[Path] = None,
+) -> int:
+    """Save a generated specification in ``pending`` status."""
+
+    LOGGER.info("Recording %s specification for project %s", spec_type, project_id)
+    try:
+        with _get_connection(db_path) as conn:
+            cursor = conn.execute(
+                """
+                INSERT INTO specifications (
+                    project_id,
+                    conversation_id,
+                    spec_type,
+                    title,
+                    content
+                ) VALUES (?, ?, ?, ?, ?)
+                """,
+                (project_id, conversation_id, spec_type, title, content),
+            )
+            conn.commit()
+            specification_id = cursor.lastrowid
+            LOGGER.debug("Specification %s stored", specification_id)
+            return specification_id
+    except sqlite3.DatabaseError as error:
+        LOGGER.exception(
+            "Failed to create specification for project %s: %s", project_id, error
+        )
+        raise
+
+
+def get_pending_specifications(
+    project_id: int,
+    db_path: Optional[Path] = None,
+) -> List[Dict[str, str]]:
+    """Return specifications awaiting approval for the given project."""
+
+    LOGGER.debug("Fetching pending specifications for project %s", project_id)
+    try:
+        with _get_connection(db_path) as conn:
+            rows = conn.execute(
+                """
+                SELECT id, spec_type, title, content, created_at
+                FROM specifications
+                WHERE project_id = ? AND status = 'pending'
+                ORDER BY created_at ASC
+                """,
+                (project_id,),
+            ).fetchall()
+            return [dict(row) for row in rows]
+    except sqlite3.DatabaseError as error:
+        LOGGER.exception(
+            "Failed to retrieve pending specifications for project %s: %s",
+            project_id,
+            error,
+        )
+        raise
+
+
+def approve_specification(spec_id: int, db_path: Optional[Path] = None) -> None:
+    """Mark a specification as approved."""
+
+    LOGGER.info("Approving specification %s", spec_id)
+    try:
+        with _get_connection(db_path) as conn:
+            conn.execute(
+                "UPDATE specifications SET status = 'approved' WHERE id = ?",
+                (spec_id,),
+            )
+            conn.commit()
+    except sqlite3.DatabaseError as error:
+        LOGGER.exception("Failed to approve specification %s: %s", spec_id, error)
+        raise
+
+
+def get_approved_specifications(
+    project_id: int,
+    spec_type: Optional[str] = None,
+    db_path: Optional[Path] = None,
+) -> List[Dict[str, str]]:
+    """Return approved specifications filtered by project and optional type."""
+
+    LOGGER.debug(
+        "Fetching approved specifications for project %s (type=%s)",
+        project_id,
+        spec_type or "*",
+    )
+    try:
+        with _get_connection(db_path) as conn:
+            if spec_type:
+                rows = conn.execute(
+                    """
+                    SELECT id, spec_type, title, content, created_at
+                    FROM specifications
+                    WHERE project_id = ? AND status = 'approved' AND spec_type = ?
+                    ORDER BY created_at DESC
+                    """,
+                    (project_id, spec_type),
+                ).fetchall()
+            else:
+                rows = conn.execute(
+                    """
+                    SELECT id, spec_type, title, content, created_at
+                    FROM specifications
+                    WHERE project_id = ? AND status = 'approved'
+                    ORDER BY created_at DESC
+                    """,
+                    (project_id,),
+                ).fetchall()
+            return [dict(row) for row in rows]
+    except sqlite3.DatabaseError as error:
+        LOGGER.exception(
+            "Failed to fetch approved specifications for project %s: %s",
+            project_id,
+            error,
+        )
+        raise
+
+
+# ---------------------------------------------------------------------------
+# Demo data
+# ---------------------------------------------------------------------------
+
+def create_sample_data(db_path: Optional[Path] = None) -> None:
+    """Populate the database with a minimal set of demo records.
+
+    This helper is intentionally idempotent – it only inserts data when the
+    database is empty.  The goal is to provide a ready-to-explore environment
+    for users trying the application without configuring API keys.
+    """
+
+    LOGGER.info("Seeding sample data if database is empty")
+    try:
+        with _get_connection(db_path) as conn:
+            cursor = conn.execute("SELECT COUNT(*) as count FROM projects")
+            count = cursor.fetchone()["count"]
+        if count:
+            LOGGER.debug("Sample data already present; skipping seed")
+            return
+
+        # Create a sample project that the UI can immediately load.
+        project_id = create_project(
+            "Demo Product",
+            "Sample workspace showcasing Naexya Docs AI capabilities",
+            db_path=db_path,
+        )
+
+        # Start one conversation per persona to demonstrate the workflow.
+        requirements_conv = create_conversation(
+            project_id, "requirements", db_path=db_path
+        )
+        technical_conv = create_conversation(
+            project_id, "technical", db_path=db_path
+        )
+
+        # Seed a few representative chat messages to illustrate history.
+        add_message(
+            requirements_conv,
+            "user",
+            "We need a mobile app for ordering office supplies with approval workflows.",
+            db_path=db_path,
+        )
+        add_message(
+            requirements_conv,
+            "assistant",
+            "Understood. I'll outline the business goals and success metrics.",
+            db_path=db_path,
+        )
+        add_message(
+            technical_conv,
+            "assistant",
+            "Suggesting a serverless backend with OAuth authentication and inventory sync.",
+            db_path=db_path,
+        )
+
+        # Finally, add a mixture of pending and approved specifications so
+        # the validation and reporting tabs have realistic content.
+        spec_id = create_specification(
+            project_id,
+            requirements_conv,
+            "Business Requirements",
+            "Ordering Experience",
+            "Employees can browse catalogues, submit carts, and track approvals.",
+            db_path=db_path,
+        )
+
+        create_specification(
+            project_id,
+            technical_conv,
+            "Technical Architecture",
+            "Solution Overview",
+            "React Native client with AWS Lambda microservices and DynamoDB storage.",
+            db_path=db_path,
+        )
+
+        # Approve one specification to show both states in the UI.
+        approve_specification(spec_id, db_path=db_path)
+
+        LOGGER.info("Sample data created successfully")
+    except sqlite3.DatabaseError as error:
+        LOGGER.exception("Failed to create sample data: %s", error)
+        raise
+
+
+# ---------------------------------------------------------------------------
+# Lightweight manager used by the Gradio interface
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SpecificationRecord:
+    """Representation of an approved specification stored for exports."""
+
+    id: int
+    title: str
+    content: str
+    created_at: str
+
+
+class DatabaseManager:
+    """Simplified database helper tailored for the Gradio UI flows."""
+
+    def __init__(self, database_path: Path):
+        self.database_path = Path(database_path)
+        init_database(self.database_path)
+
+    def save_specification(self, title: str, content: str) -> int:
+        """Persist an approved specification for later browsing and export."""
+
+        LOGGER.info("Persisting approved specification: %s", title)
+        try:
+            with _get_connection(self.database_path) as conn:
+                cursor = conn.execute(
+                    "INSERT INTO approved_specs (title, content) VALUES (?, ?)",
+                    (title, content),
+                )
+                conn.commit()
+                spec_id = int(cursor.lastrowid)
+                LOGGER.debug("Approved specification stored with id %s", spec_id)
+                return spec_id
+        except sqlite3.DatabaseError as error:
+            LOGGER.exception("Failed to store approved specification '%s': %s", title, error)
+            raise
+
+    def fetch_recent_specifications(self, limit: int = 50) -> List[SpecificationRecord]:
+        """Return the most recently stored approved specifications."""
+
+        LOGGER.debug("Fetching up to %s approved specifications", limit)
+        try:
+            with _get_connection(self.database_path) as conn:
+                rows = conn.execute(
+                    """
+                    SELECT id, title, content, created_at
+                    FROM approved_specs
+                    ORDER BY created_at DESC
+                    LIMIT ?
+                    """,
+                    (limit,),
+                ).fetchall()
+            return [
+                SpecificationRecord(
+                    id=int(row["id"]),
+                    title=str(row["title"]),
+                    content=str(row["content"]),
+                    created_at=str(row["created_at"]),
+                )
+                for row in rows
+            ]
+        except sqlite3.DatabaseError as error:
+            LOGGER.exception("Failed to fetch approved specifications: %s", error)
+            raise
+
+
+# Ensure the schema exists whenever this module is imported.  This keeps the
+# rest of the application simple because it can assume the tables are present.
+init_database()
+
+
+__all__ = [
+    "DATABASE_PATH",
+    "DatabaseManager",
+    "SpecificationRecord",
+    "init_database",
+    "create_project",
+    "get_projects",
+    "create_conversation",
+    "add_message",
+    "lock_conversation",
+    "create_specification",
+    "get_pending_specifications",
+    "approve_specification",
+    "get_approved_specifications",
+    "create_sample_data",
+]
+

requirements.txt

@@ -0,0 +1,23 @@
+# Requirements for running the Naexya Docs AI Gradio application.
+# Each dependency below is documented to explain its role in the project.
+#
+# gradio powers the web-based interface that enables users to interact with
+# AI specification tools directly from the browser with minimal boilerplate.
+gradio==4.0.0
+# requests provides a simple yet powerful HTTP client for calling external AI
+# services that do not have dedicated SDKs, ensuring consistent API handling.
+requests==2.31.0
+# sqlite3 is part of the Python standard library and powers lightweight local
+# storage for specifications; the entry here serves as documentation only.
+# No pip installation is required because sqlite3 ships with Python 3.
+# sqlite3
+# python-dotenv loads environment variables from a .env file, simplifying
+# configuration management for different environments (development, staging,
+# production) without hardcoding secrets in the codebase.
+python-dotenv==1.0.1
+# markdown converts project specifications into Markdown-formatted text for
+# exports and previews inside the application and supporting services.
+markdown==3.5.2
+# jinja2 renders HTML and Markdown export templates with dynamic content,
+# allowing flexible formatting of generated specification documents.
+jinja2==3.1.3

templates/export_html.html

@@ -0,0 +1,537 @@
+<!--
+    Professional export template for Naexya Docs AI.
+    This template is rendered via Jinja2 using context prepared in utils.generate_export_html.
+    Extensive comments describe each major block so designers can tweak branding or structure.
+-->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{ project_name }} – Specification Export | {{ brand_name }}</title>
+    <!--
+        Embedded stylesheet uses CSS variables for easy brand customization and
+        ensures the layout adapts gracefully for both screens and printed copies.
+    -->
+    <style>
+        :root {
+            --brand-primary: #1f3c88;
+            --brand-secondary: #19a974;
+            --brand-accent: #f5f7fb;
+            --text-color: #1f1f1f;
+            --muted-text: #5f6c7b;
+            --border-color: #d9e1ec;
+            --card-shadow: 0 12px 24px rgba(15, 34, 58, 0.08);
+            --font-family: "Inter", "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+        }
+
+        * {
+            box-sizing: border-box;
+        }
+
+        body {
+            margin: 0;
+            padding: 0;
+            font-family: var(--font-family);
+            background: #ffffff;
+            color: var(--text-color);
+            line-height: 1.6;
+        }
+
+        .page {
+            max-width: 960px;
+            margin: 0 auto;
+            padding: 2.5rem 1.75rem 3.5rem;
+        }
+
+        /*
+            Header block contains brand identity and key project metadata.
+            Flex layout ensures the section remains responsive.
+        */
+        .export-header {
+            display: flex;
+            flex-wrap: wrap;
+            align-items: flex-start;
+            gap: 1.5rem;
+            padding: 2rem;
+            border-radius: 18px;
+            background: linear-gradient(135deg, rgba(31, 60, 136, 0.92), rgba(25, 169, 116, 0.85));
+            color: #ffffff;
+            box-shadow: var(--card-shadow);
+        }
+
+        .export-header .branding {
+            flex: 1 1 240px;
+        }
+
+        .export-header h1 {
+            margin: 0;
+            font-size: 2.25rem;
+            letter-spacing: 0.04em;
+        }
+
+        .export-header .tagline {
+            margin: 0.35rem 0 0;
+            font-size: 1rem;
+            opacity: 0.9;
+        }
+
+        .project-meta {
+            flex: 2 1 320px;
+            background: rgba(255, 255, 255, 0.15);
+            border-radius: 14px;
+            padding: 1.25rem 1.5rem;
+            backdrop-filter: blur(4px);
+        }
+
+        .project-meta h2 {
+            margin: 0 0 0.75rem;
+            font-size: 1.65rem;
+        }
+
+        .project-meta p {
+            margin: 0 0 1rem;
+            color: #f1f5fb;
+        }
+
+        .project-meta dl {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+            gap: 0.75rem;
+            margin: 0;
+        }
+
+        .project-meta dt {
+            font-weight: 600;
+            font-size: 0.85rem;
+            text-transform: uppercase;
+            letter-spacing: 0.08em;
+            opacity: 0.75;
+        }
+
+        .project-meta dd {
+            margin: 0;
+            font-size: 1rem;
+        }
+
+        /*
+            Statistics grid highlights counts and health metrics using cards so
+            stakeholders can absorb the state of the project at a glance.
+        */
+        .statistics-section {
+            margin: 2.75rem 0;
+        }
+
+        .statistics-section h2 {
+            margin-bottom: 1rem;
+            font-size: 1.5rem;
+            color: var(--brand-primary);
+        }
+
+        .statistics-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+            gap: 1rem;
+        }
+
+        .stat-card {
+            background: var(--brand-accent);
+            border-radius: 14px;
+            padding: 1.25rem 1.5rem;
+            box-shadow: var(--card-shadow);
+        }
+
+        .stat-card.span-2 {
+            grid-column: span 2;
+        }
+
+        .stat-label {
+            display: block;
+            font-size: 0.85rem;
+            text-transform: uppercase;
+            letter-spacing: 0.08em;
+            color: var(--muted-text);
+        }
+
+        .stat-value {
+            display: block;
+            margin-top: 0.35rem;
+            font-size: 1.8rem;
+            font-weight: 700;
+            color: var(--brand-primary);
+        }
+
+        .status-list {
+            list-style: none;
+            margin: 0.75rem 0 0;
+            padding: 0;
+        }
+
+        .status-list li {
+            display: flex;
+            justify-content: space-between;
+            padding: 0.35rem 0;
+            border-bottom: 1px dashed rgba(31, 60, 136, 0.2);
+        }
+
+        .status-name {
+            font-weight: 600;
+        }
+
+        .status-count {
+            font-variant-numeric: tabular-nums;
+            color: var(--brand-primary);
+        }
+
+        /*
+            Navigation panel offers quick jumps to each specification category.
+            Anchors reuse the slugified IDs produced by utils._slugify.
+        */
+        .table-of-contents {
+            margin: 3rem 0 2rem;
+            padding: 1.75rem 2rem;
+            border-radius: 16px;
+            border: 1px solid var(--border-color);
+            background: #ffffff;
+            box-shadow: var(--card-shadow);
+        }
+
+        .table-of-contents h2 {
+            margin-top: 0;
+            color: var(--brand-primary);
+            font-size: 1.45rem;
+        }
+
+        .toc-list {
+            margin: 1.25rem 0 0;
+            padding: 0;
+            list-style: none;
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+            gap: 0.75rem 1.25rem;
+        }
+
+        .toc-list li a {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            padding: 0.75rem 0.95rem;
+            border-radius: 12px;
+            text-decoration: none;
+            color: var(--text-color);
+            background: #f9fbff;
+            border: 1px solid transparent;
+            transition: all 0.2s ease;
+        }
+
+        .toc-list li a:hover,
+        .toc-list li a:focus {
+            border-color: var(--brand-primary);
+            box-shadow: 0 0 0 3px rgba(31, 60, 136, 0.15);
+        }
+
+        .toc-count {
+            font-weight: 600;
+            color: var(--brand-primary);
+        }
+
+        /*
+            Main specification sections are rendered using <section> and <article>
+            with cards for each approved specification entry.
+        */
+        .specification-sections {
+            display: flex;
+            flex-direction: column;
+            gap: 2.5rem;
+        }
+
+        .spec-section {
+            padding: 2rem 2.25rem;
+            border-radius: 18px;
+            background: #ffffff;
+            border: 1px solid var(--border-color);
+            box-shadow: var(--card-shadow);
+        }
+
+        .spec-section.empty {
+            text-align: center;
+            color: var(--muted-text);
+        }
+
+        .section-header {
+            display: flex;
+            flex-wrap: wrap;
+            gap: 0.75rem;
+            justify-content: space-between;
+            align-items: center;
+            margin-bottom: 1.5rem;
+        }
+
+        .section-header h2 {
+            margin: 0;
+            font-size: 1.6rem;
+            color: var(--brand-primary);
+        }
+
+        .badge {
+            display: inline-flex;
+            align-items: center;
+            justify-content: center;
+            min-width: 2.5rem;
+            padding: 0.35rem 0.75rem;
+            border-radius: 999px;
+            background: rgba(31, 60, 136, 0.08);
+            color: var(--brand-primary);
+            font-weight: 600;
+            font-size: 0.85rem;
+        }
+
+        .spec-card {
+            margin-bottom: 1.65rem;
+            padding: 1.5rem 1.75rem;
+            border-radius: 14px;
+            border: 1px solid rgba(31, 60, 136, 0.1);
+            background: #fdfefe;
+            transition: transform 0.2s ease;
+        }
+
+        .spec-card:hover {
+            transform: translateY(-2px);
+        }
+
+        .spec-card h3 {
+            margin: 0 0 0.75rem;
+            font-size: 1.35rem;
+            color: var(--text-color);
+        }
+
+        .spec-meta {
+            display: flex;
+            flex-wrap: wrap;
+            gap: 0.75rem 1.5rem;
+            align-items: center;
+            margin-bottom: 1rem;
+            color: var(--muted-text);
+            font-size: 0.95rem;
+        }
+
+        .status-pill {
+            padding: 0.35rem 0.85rem;
+            border-radius: 999px;
+            background: rgba(25, 169, 116, 0.12);
+            color: #198754;
+            font-weight: 600;
+            text-transform: uppercase;
+            letter-spacing: 0.04em;
+            font-size: 0.75rem;
+        }
+
+        .status-pending {
+            background: rgba(255, 193, 7, 0.18);
+            color: #ad7a00;
+        }
+
+        .status-approved {
+            background: rgba(25, 169, 116, 0.15);
+            color: #146c43;
+        }
+
+        .status-rejected {
+            background: rgba(220, 53, 69, 0.15);
+            color: #842029;
+        }
+
+        .conversation-link {
+            color: var(--brand-primary);
+            text-decoration: none;
+            font-weight: 600;
+        }
+
+        .conversation-link:hover,
+        .conversation-link:focus {
+            text-decoration: underline;
+        }
+
+        .spec-body p {
+            margin: 0 0 0.85rem;
+        }
+
+        .spec-body em {
+            color: var(--muted-text);
+        }
+
+        /*
+            Conversation reference list provides anchors back to the originating
+            chats or external systems. Designers can re-point the base URL using
+            project_data["conversation_base_url"].
+        */
+        .conversation-section {
+            margin: 3rem 0;
+            padding: 2rem 2.25rem;
+            border-radius: 16px;
+            border: 1px solid var(--border-color);
+            background: var(--brand-accent);
+        }
+
+        .conversation-section h2 {
+            margin-top: 0;
+            font-size: 1.5rem;
+            color: var(--brand-primary);
+        }
+
+        .conversation-list {
+            list-style: none;
+            margin: 1.25rem 0 0;
+            padding: 0;
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+            gap: 0.85rem;
+        }
+
+        .conversation-list a {
+            display: block;
+            padding: 0.75rem 0.95rem;
+            border-radius: 12px;
+            background: #ffffff;
+            border: 1px solid rgba(31, 60, 136, 0.12);
+            color: var(--brand-primary);
+            font-weight: 600;
+            text-decoration: none;
+        }
+
+        .conversation-list a:hover,
+        .conversation-list a:focus {
+            border-color: var(--brand-primary);
+            box-shadow: 0 0 0 3px rgba(31, 60, 136, 0.15);
+        }
+
+        /*
+            Footer summarises export metadata for auditing and printouts.
+        */
+        footer {
+            margin-top: 3.5rem;
+            padding-top: 1.5rem;
+            border-top: 1px solid var(--border-color);
+            color: var(--muted-text);
+            font-size: 0.9rem;
+            text-align: center;
+        }
+
+        /*
+            Responsive adjustments ensure comfortable reading on tablets and phones.
+        */
+        @media (max-width: 768px) {
+            .page {
+                padding: 2rem 1.25rem 3rem;
+            }
+
+            .export-header {
+                padding: 1.75rem;
+            }
+
+            .project-meta {
+                padding: 1rem 1.25rem;
+            }
+
+            .spec-section {
+                padding: 1.5rem 1.6rem;
+            }
+
+            .table-of-contents {
+                padding: 1.5rem 1.6rem;
+            }
+        }
+
+        /*
+            Print rules remove shadows and adjust spacing for crisp documents.
+        */
+        @media print {
+            body {
+                color: #000000;
+            }
+
+            .page {
+                max-width: none;
+                padding: 1.25rem;
+            }
+
+            .export-header,
+            .spec-section,
+            .table-of-contents,
+            .conversation-section,
+            .stat-card {
+                box-shadow: none;
+            }
+
+            .spec-card {
+                border: 1px solid #cccccc;
+                page-break-inside: avoid;
+            }
+
+            footer {
+                page-break-inside: avoid;
+            }
+        }
+    </style>
+</head>
+<body>
+    <div class="page">
+        <!-- Header: brand identity and core project metadata. -->
+        <header class="export-header">
+            <div class="branding">
+                <h1>{{ brand_name }}</h1>
+                <p class="tagline">Project Specification Portfolio</p>
+            </div>
+            <div class="project-meta">
+                <h2>{{ project_name }}</h2>
+                {% if project_description %}
+                <p>{{ project_description }}</p>
+                {% endif %}
+                <dl>
+                    <div>
+                        <dt>Project ID</dt>
+                        <dd>{{ project_identifier }}</dd>
+                    </div>
+                    <div>
+                        <dt>Created</dt>
+                        <dd>{% if project_created_at %}{{ project_created_at }}{% else %}Not available{% endif %}</dd>
+                    </div>
+                    <div>
+                        <dt>Total Specifications</dt>
+                        <dd>{{ specification_total }}</dd>
+                    </div>
+                    <div>
+                        <dt>Last Activity</dt>
+                        <dd>{% if latest_activity %}{{ latest_activity }}{% else %}Not available{% endif %}</dd>
+                    </div>
+                </dl>
+            </div>
+        </header>
+
+        <!-- Statistics summary: rendered from utils._build_statistics_block. -->
+        <section class="statistics-section">
+            <h2>Project Overview</h2>
+            {{ statistics_block }}
+        </section>
+
+        <!-- Table of contents with quick links to each specification category. -->
+        <nav class="table-of-contents" aria-label="Specification categories">
+            <h2>Table of Contents</h2>
+            {{ table_of_contents }}
+        </nav>
+
+        <!-- Main specification content grouped by type. -->
+        <main class="specification-sections">
+            {{ specification_sections }}
+        </main>
+
+        <!-- Linked conversation references encourage reviewers to trace context. -->
+        {{ conversation_references }}
+
+        <!-- Footer summarises export provenance. -->
+        <footer>
+            Generated on {{ generated_at }} by {{ brand_name }}.
+        </footer>
+    </div>
+</body>
+</html>

templates/export_markdown.md

@@ -0,0 +1,67 @@
+<!--
+    Markdown export template optimised for AI coding agents.
+    Structured front matter ensures downstream tools can parse metadata while
+    the main body mirrors specification categories with consistent headings.
+-->
+---
+project_id: {{ metadata.project_id }}
+project_created_at: {{ metadata.project_created_at }}
+generation_timestamp: {{ generation_date }}
+specification_totals:
+  overall: {{ spec_count }}
+{% if metadata.spec_counts %}
+  by_type:
+{% for entry in metadata.spec_counts %}    - type: {{ entry.type }}
+      count: {{ entry.count }}
+{% endfor %}
+{% else %}
+  by_type: []
+{% endif %}
+status_breakdown:
+{% if metadata.status_counts %}
+{% for entry in metadata.status_counts %}  - status: {{ entry.status }}
+    count: {{ entry.count }}
+{% endfor %}
+{% else %}  - status: none recorded
+    count: 0
+{% endif %}
+latest_activity: {{ metadata.latest_activity }}
+conversation_links:
+{% if metadata.conversation_links %}
+{% for link in metadata.conversation_links %}  - id: {{ link.id }}
+    url: {{ link.url }}
+{% endfor %}
+{% else %}
+  []
+{% endif %}
+---
+# Project: {{ project_name }}
+
+## Overview
+- Description: {{ project_description }}
+- Generated: {{ generation_date }}
+- Total Specifications: {{ spec_count }}
+
+## User Stories
+{{ user_stories_section }}
+
+## Features
+{{ features_section }}
+
+## API Endpoints
+{{ api_endpoints_section }}
+
+## Database Design
+{{ database_design_section }}
+
+## System Architecture
+{{ system_architecture_section }}
+
+## Implementation Notes
+{{ implementation_notes }}
+
+{% if additional_sections %}## Additional Categories
+{{ additional_sections }}
+{% endif %}
+
+<!-- End of export template -->

utils.py

@@ -0,0 +1,898 @@
+"""Utility helpers used across the Naexya Docs AI application.
+
+The project pulls together configuration, database persistence, and a Gradio
+interface.  This module keeps shared helper functions in one place so they can
+be reused by both the UI and background processes.  Each function includes
+extensive documentation that explains the intended behaviour, common edge
+cases, and recommended extension points.
+"""
+
+from __future__ import annotations
+
+import html
+import json
+import logging
+import re
+import sqlite3
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Set, Tuple
+
+try:  # ``jinja2`` is optional at runtime but recommended for template rendering.
+    from jinja2 import Template
+except ImportError:  # pragma: no cover - executed only when dependency missing.
+    Template = None  # type: ignore[misc]
+
+from config import AI_PROVIDERS, EXPORT_TEMPLATES, SPECIFICATION_TYPES
+from database import DATABASE_PATH
+
+# Configure a dedicated logger so user action tracking and validation warnings
+# can be filtered or redirected by the application-wide logging configuration.
+LOGGER = logging.getLogger(__name__)
+
+# Resolve repository root and template directory.  ``BASE_DIR`` allows us to
+# construct absolute paths for template loading even when the application is
+# executed from a different working directory (e.g. when packaged as a module).
+BASE_DIR = Path(__file__).resolve().parent
+TEMPLATES_DIR = BASE_DIR / "templates"
+
+# Mapping of canonical specification categories to Markdown template placeholders.
+MARKDOWN_SECTION_KEYS: Dict[str, str] = {
+    "User Stories": "user_stories_section",
+    "Features": "features_section",
+    "API Endpoints": "api_endpoints_section",
+    "Database Design": "database_design_section",
+    "System Architecture": "system_architecture_section",
+}
+
+
+# ---------------------------------------------------------------------------
+# Input validation helpers
+# ---------------------------------------------------------------------------
+
+def validate_api_key(provider: str, api_key: str) -> bool:
+    """Perform lightweight validation of an API key for a given provider.
+
+    The function does **not** make external HTTP requests.  Instead it checks
+    that the provider exists in :mod:`config`, ensures a key was supplied, and
+    verifies that it is of a plausible length.  Applications can call this when
+    a user enters credentials to provide immediate feedback before attempting a
+    full API call.
+
+    Args:
+        provider: Provider identifier matching a key in ``AI_PROVIDERS``.
+        api_key: Raw string provided by the end user.
+
+    Returns:
+        ``True`` when the key passes basic validation.  ``False`` is returned
+        when validation fails but the caller prefers to handle messaging
+        without exceptions.
+
+    Raises:
+        ValueError: If the provider is unknown or the key is blank.
+    """
+
+    if provider not in AI_PROVIDERS:
+        raise ValueError(
+            f"Provider '{provider}' is not recognised. Please choose one of: "
+            f"{', '.join(sorted(AI_PROVIDERS))}."
+        )
+
+    if not isinstance(api_key, str) or not api_key.strip():
+        raise ValueError("API key must be a non-empty string.")
+
+    cleaned = api_key.strip()
+    if len(cleaned) < 8:
+        LOGGER.warning(
+            "API key for provider '%s' appears unusually short.", provider
+        )
+        return False
+
+    # Many providers rely on Authorization headers containing ``{api_key}``.
+    header_format = AI_PROVIDERS[provider]["headers"].get("Authorization", "")
+    if "{api_key}" not in header_format:
+        LOGGER.debug(
+            "Provider '%s' does not use a standard Authorization header template.",
+            provider,
+        )
+
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Conversation formatting
+# ---------------------------------------------------------------------------
+
+def format_conversation_history(
+    messages: Sequence[Mapping[str, Any]]
+) -> str:
+    """Create a readable transcript from stored conversation messages.
+
+    Each message mapping should contain at minimum ``role`` and ``content``
+    keys, with ``timestamp`` being optional.  ``format_conversation_history``
+    sorts the messages chronologically (when timestamps are available) and
+    returns a newline-delimited string ready for display in the Gradio
+    interface or export templates.
+
+    Args:
+        messages: Iterable of dictionary-like objects representing chat turns.
+
+    Returns:
+        A human-friendly string.  When no messages are provided a helpful
+        placeholder message is returned instead of an empty string.
+    """
+
+    if not messages:
+        return "No conversation history available yet."
+
+    def _sort_key(message: Mapping[str, Any]):
+        ts = message.get("timestamp")
+        if isinstance(ts, datetime):
+            return (0, ts)
+        if isinstance(ts, str):
+            try:
+                parsed = datetime.fromisoformat(ts)
+                return (0, parsed)
+            except ValueError:
+                return (1, ts)
+        return (2, "")
+
+    sorted_messages = sorted(messages, key=_sort_key)
+
+    formatted_lines = []
+    for entry in sorted_messages:
+        role = str(entry.get("role", "unknown")).title()
+        timestamp = entry.get("timestamp")
+        human_time = f" [{timestamp}]" if timestamp else ""
+        content = entry.get("content", "")
+        if not isinstance(content, str):
+            content = str(content)
+        formatted_lines.append(f"{role}{human_time}:\n{content.strip()}\n")
+
+    return "\n".join(formatted_lines).strip()
+
+
+# ---------------------------------------------------------------------------
+# Export helpers
+# ---------------------------------------------------------------------------
+
+def _render_template(path: Path, context: Mapping[str, Any]) -> str:
+    """Render a template file using Jinja2 when available.
+
+    This private helper keeps file reading and template rendering consistent for
+    both HTML and Markdown exports.  When :mod:`jinja2` is unavailable the
+    function gracefully falls back to Python's :py:meth:`str.format` syntax,
+    ensuring the application still works albeit without advanced templating
+    features like loops or conditionals.
+    """
+
+    if not path.exists():
+        raise FileNotFoundError(f"Template file '{path}' was not found.")
+
+    template_text = path.read_text(encoding="utf-8")
+
+    if Template is None:
+        LOGGER.warning(
+            "jinja2 is not installed; falling back to basic placeholder replacement for %s",
+            path,
+        )
+        if "{%" in template_text or "%}" in template_text:
+            raise RuntimeError(
+                "The export template requires jinja2 for conditional rendering. Install jinja2 to continue."
+            )
+        rendered = template_text
+        for key, value in context.items():
+            rendered = rendered.replace(f"{{{{{key}}}}}", str(value))
+        return rendered
+
+    return Template(template_text).render(**context)
+
+
+def format_prompt(prompt: str) -> str:
+    """Normalise user prompts before sending them to a provider."""
+
+    if not isinstance(prompt, str):
+        raise ValueError("Prompt must be provided as a string.")
+
+    cleaned = sanitize_input(prompt)
+    if not cleaned:
+        raise ValueError("Prompt cannot be empty after sanitisation.")
+    return cleaned
+
+
+def render_export(template_name: str, context: Mapping[str, Any]) -> str:
+    """Load a template from ``templates/`` and render it with ``context``."""
+
+    if not template_name or not isinstance(template_name, str):
+        raise ValueError("Template name must be a non-empty string.")
+
+    template_path = Path(template_name)
+    if not template_path.is_absolute():
+        template_path = TEMPLATES_DIR / template_path
+
+    return _render_template(template_path, context)
+
+
+def _group_specifications(
+    specifications: Sequence[Mapping[str, Any]]
+) -> Dict[str, List[Mapping[str, Any]]]:
+    """Organise specification rows by their ``spec_type`` value."""
+
+    grouped: Dict[str, List[Mapping[str, Any]]] = {}
+    for spec in specifications:
+        spec_type = str(spec.get("spec_type") or "Uncategorised")
+        grouped.setdefault(spec_type, []).append(spec)
+    return grouped
+
+
+def _prepare_html_export_context(
+    project_data: Mapping[str, Any],
+    specifications: Sequence[Mapping[str, Any]],
+) -> Dict[str, Any]:
+    """Assemble template context for the HTML export."""
+
+    brand_name = str(project_data.get("brand_name") or "Naexya Docs AI").strip() or "Naexya Docs AI"
+    project_name = str(project_data.get("name") or "Untitled Project").strip() or "Untitled Project"
+    description_raw = project_data.get("description")
+    project_description = (
+        html.escape(str(description_raw).strip()) if description_raw else ""
+    )
+    project_created_at = _format_datetime_for_display(project_data.get("created_at"))
+    project_identifier = html.escape(str(project_data.get("id") or "N/A"))
+
+    grouped = _group_specifications(specifications)
+    ordered_types: List[str] = list(SPECIFICATION_TYPES)
+    for spec_type in grouped.keys():
+        if spec_type not in ordered_types:
+            ordered_types.append(spec_type)
+
+    counts_by_type: Dict[str, int] = {spec_type: len(grouped.get(spec_type, [])) for spec_type in ordered_types}
+    total_specs = sum(counts_by_type.values())
+
+    status_counts: Dict[str, int] = defaultdict(int)
+    timestamp_candidates: List[datetime] = []
+    for items in grouped.values():
+        for spec in items:
+            status = str(spec.get("status") or "pending").strip().lower()
+            status_counts[status] += 1
+            parsed = _parse_datetime(spec.get("created_at"))
+            if parsed is not None:
+                timestamp_candidates.append(parsed)
+
+    latest_activity = _format_datetime_for_display(max(timestamp_candidates)) if timestamp_candidates else "Not available"
+
+    table_of_contents = _build_table_of_contents(ordered_types, counts_by_type)
+    conversation_base_url = str(project_data.get("conversation_base_url") or "").strip()
+    sections_html, conversation_ids = _build_specification_sections(
+        grouped, ordered_types, conversation_base_url
+    )
+    statistics_block = _build_statistics_block(total_specs, counts_by_type, status_counts, latest_activity)
+    conversation_references = _build_conversation_reference_section(
+        conversation_ids, conversation_base_url
+    )
+
+    return {
+        "brand_name": brand_name,
+        "project_name": html.escape(project_name),
+        "project_description": project_description,
+        "project_created_at": project_created_at,
+        "project_identifier": project_identifier,
+        "specification_total": total_specs,
+        "table_of_contents": table_of_contents,
+        "specification_sections": sections_html,
+        "statistics_block": statistics_block,
+        "conversation_references": conversation_references,
+        "latest_activity": latest_activity,
+    }
+
+
+def _build_table_of_contents(spec_types: Sequence[str], counts: Mapping[str, int]) -> str:
+    """Create an ordered list linking to each specification section."""
+
+    if not spec_types:
+        return (
+            "<p class=\"empty-state\">No specification categories are configured. "
+            "Update SPECIFICATION_TYPES to populate the table of contents.</p>"
+        )
+
+    lines = ["<ol class=\"toc-list\">"]
+    for spec_type in spec_types:
+        slug = _slugify(spec_type)
+        count = counts.get(spec_type, 0)
+        lines.append(
+            "  <li>"
+            f"<a href=\"#{slug}\">"
+            f"<span class=\"toc-title\">{html.escape(spec_type)}</span>"
+            f"<span class=\"toc-count\">{count}</span>"
+            "</a>"
+            "</li>"
+        )
+    lines.append("</ol>")
+    return "\n".join(lines)
+
+
+def _build_specification_sections(
+    grouped: Mapping[str, Sequence[Mapping[str, Any]]],
+    ordered_types: Sequence[str],
+    conversation_base_url: str,
+) -> Tuple[str, Set[str]]:
+    """Render each specification category into HTML sections."""
+
+    sections: List[str] = []
+    conversation_ids: Set[str] = set()
+
+    if not grouped:
+        sections.append(
+            "<section class=\"spec-section empty\">"
+            "<p>No specifications have been captured yet. Approve drafts to populate this report.</p>"
+            "</section>"
+        )
+        return "\n".join(sections), conversation_ids
+
+    for spec_type in ordered_types:
+        items = list(grouped.get(spec_type, []))
+        slug = _slugify(spec_type)
+        sections.append(f"<section id=\"{slug}\" class=\"spec-section\">")
+        header_html = (
+            "  <header class=\"section-header\">"
+            f"<h2>{html.escape(spec_type)}</h2>"
+            f"<span class=\"badge\">{len(items)} items</span>"
+            "</header>"
+        )
+        sections.append(header_html)
+
+        if not items:
+            sections.append(
+                "  <p class=\"empty-state\">No specifications approved for this category yet.</p>"
+            )
+            sections.append("</section>")
+            continue
+
+        for spec in items:
+            title = html.escape(str(spec.get("title") or "Untitled").strip() or "Untitled")
+            raw_status = str(spec.get("status") or "pending").strip() or "pending"
+            status_label = html.escape(raw_status.replace("_", " ").title())
+            status_class = _slugify(raw_status)
+            created_display = _format_datetime_for_display(spec.get("created_at"))
+            conversation_id = spec.get("conversation_id")
+            conversation_link = ""
+            if conversation_id is not None:
+                identifier = str(conversation_id)
+                conversation_ids.add(identifier)
+                link_href = _build_conversation_link(conversation_base_url, identifier)
+                link_text = html.escape(identifier)
+                conversation_link = (
+                    f'<a class="conversation-link" href="{link_href}">'
+                    f'View source conversation #{link_text}</a>'
+                )
+
+            body_html = _render_rich_text(str(spec.get("content") or ""))
+
+            sections.append("  <article class=\"spec-card\">")
+            sections.append(f"    <h3>{title}</h3>")
+            sections.append("    <div class=\"spec-meta\">")
+            sections.append(
+                f"      <span class=\"status-pill status-{status_class}\">{status_label}</span>"
+            )
+            if created_display:
+                sections.append(
+                    f"      <span class=\"timestamp\">Captured: {created_display}</span>"
+                )
+            if conversation_link:
+                sections.append(f"      {conversation_link}")
+            sections.append("    </div>")
+            sections.append(f"    <div class=\"spec-body\">{body_html}</div>")
+            sections.append("  </article>")
+
+        sections.append("</section>")
+
+    return "\n".join(sections), conversation_ids
+
+
+def _build_statistics_block(
+    total_specs: int,
+    counts_by_type: Mapping[str, int],
+    status_counts: Mapping[str, int],
+    latest_activity: str,
+) -> str:
+    """Summarise key metrics for the exported project."""
+
+    cards: List[str] = ["<div class=\"statistics-grid\">"]
+    cards.append(
+        "  <div class=\"stat-card\">"
+        "<span class=\"stat-label\">Total Specifications</span>"
+        f"<span class=\"stat-value\">{total_specs}</span>"
+        "</div>"
+    )
+
+    for spec_type, count in counts_by_type.items():
+        cards.append(
+            "  <div class=\"stat-card\">"
+            f"<span class=\"stat-label\">{html.escape(spec_type)}</span>"
+            f"<span class=\"stat-value\">{count}</span>"
+            "</div>"
+        )
+
+    if status_counts:
+        status_items: List[str] = []
+        for status, count in sorted(status_counts.items()):
+            status_items.append(
+                "<li>"
+                f"<span class=\"status-name\">{html.escape(status.replace('_', ' ').title())}</span>"
+                f"<span class=\"status-count\">{count}</span>"
+                "</li>"
+            )
+        cards.append(
+            "  <div class=\"stat-card span-2\">"
+            "<span class=\"stat-label\">By Status</span>"
+            f"<ul class=\"status-list\">{''.join(status_items)}</ul>"
+            "</div>"
+        )
+
+    cards.append(
+        "  <div class=\"stat-card span-2\">"
+        "<span class=\"stat-label\">Last Updated</span>"
+        f"<span class=\"stat-value\">{latest_activity}</span>"
+        "</div>"
+    )
+
+    cards.append("</div>")
+    return "\n".join(cards)
+
+
+def _build_conversation_reference_section(
+    conversation_ids: Set[str], conversation_base_url: str
+) -> str:
+    """Generate a section listing links back to the originating conversations."""
+
+    header = "<section id=\"conversation-references\" class=\"conversation-section\">"
+    header += "<h2>Conversation References</h2>"
+
+    if not conversation_ids:
+        return (
+            header
+            + "<p>No linked conversations were captured for these specifications. Continue collaborating to enrich this section.</p>"
+            + "</section>"
+        )
+
+    items: List[str] = []
+    for identifier in sorted(conversation_ids, key=lambda value: (len(value), value)):
+        href = _build_conversation_link(conversation_base_url, identifier)
+        items.append(
+            f"<li><a href=\"{href}\">Conversation #{html.escape(identifier)}</a></li>"
+        )
+
+    return header + "<ul class=\"conversation-list\">" + "".join(items) + "</ul></section>"
+
+
+def _build_conversation_link(base_url: str, conversation_id: Any) -> str:
+    """Return a safe hyperlink for a conversation reference."""
+
+    identifier = str(conversation_id)
+    if base_url:
+        href = f"{base_url.rstrip('/')}/{identifier}"
+    else:
+        href = f"#conversation-{identifier}"
+    return html.escape(href, quote=True)
+
+
+def _render_rich_text(content: str) -> str:
+    """Convert plain text into minimal HTML while preserving structure."""
+
+    stripped = content.strip()
+    if not stripped:
+        return "<p><em>No additional details provided.</em></p>"
+
+    escaped = html.escape(stripped)
+    paragraphs = [para for para in escaped.split("\n\n") if para]
+    if not paragraphs:
+        paragraphs = [escaped]
+
+    formatted: List[str] = []
+    for paragraph in paragraphs:
+        formatted.append("<p>" + paragraph.replace("\n", "<br />") + "</p>")
+    return "\n".join(formatted)
+
+
+def _parse_datetime(value: Any) -> Optional[datetime]:
+    """Safely parse a datetime from various formats used in the database."""
+
+    if isinstance(value, datetime):
+        dt = value
+    elif isinstance(value, str):
+        candidate = value.strip()
+        if not candidate:
+            return None
+        try:
+            dt = datetime.fromisoformat(candidate)
+        except ValueError:
+            return None
+    else:
+        return None
+
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+def _format_datetime_for_display(value: Any) -> str:
+    """Render a datetime value in a human-friendly string."""
+
+    parsed = _parse_datetime(value)
+    if parsed is None:
+        if isinstance(value, str) and value.strip():
+            return html.escape(value.strip())
+        return ""
+
+    display = parsed.astimezone(timezone.utc).strftime("%d %B %Y %H:%M %Z")
+    return html.escape(display)
+
+
+def _slugify(value: str) -> str:
+    """Convert arbitrary text into an anchor-friendly slug."""
+
+    slug = re.sub(r"[^a-z0-9]+", "-", value.lower())
+    slug = slug.strip("-")
+    return slug or "section"
+
+
+def _build_markdown_context(
+    project_data: Mapping[str, Any],
+    specifications: Sequence[Mapping[str, Any]],
+    generated_at: str,
+) -> Dict[str, Any]:
+    """Assemble structured context for the Markdown export template."""
+
+    project_name = (
+        str(project_data.get("name") or "Untitled Project").strip() or "Untitled Project"
+    )
+    description_raw = project_data.get("description")
+    project_description = (
+        str(description_raw).strip() if description_raw and str(description_raw).strip() else "Not provided."
+    )
+    conversation_base_url = str(project_data.get("conversation_base_url") or "").strip()
+
+    project_identifier = str(project_data.get("id") or "N/A")
+    created_dt = _parse_datetime(project_data.get("created_at"))
+    project_created_at = (
+        created_dt.astimezone(timezone.utc).isoformat() if created_dt else "not_recorded"
+    )
+
+    grouped = _group_specifications(specifications)
+    ordered_types: List[str] = list(SPECIFICATION_TYPES)
+    for spec_type in grouped:
+        if spec_type not in ordered_types:
+            ordered_types.append(spec_type)
+
+    spec_counts = [
+        {"type": spec_type, "count": len(grouped.get(spec_type, []))}
+        for spec_type in ordered_types
+    ]
+    total_specs = sum(entry["count"] for entry in spec_counts)
+
+    status_totals: Dict[str, int] = defaultdict(int)
+    conversation_links: List[Dict[str, str]] = []
+    seen_conversations: Set[str] = set()
+    latest_candidates: List[datetime] = []
+
+    sections: Dict[str, str] = {
+        placeholder: f"_No {category} documented yet._"
+        for category, placeholder in MARKDOWN_SECTION_KEYS.items()
+    }
+    additional_section_blocks: List[str] = []
+
+    for spec_type in ordered_types:
+        items = list(grouped.get(spec_type, []))
+
+        for spec in items:
+            status = str(spec.get("status") or "pending").strip() or "pending"
+            status_totals[status] += 1
+
+            created = _parse_datetime(spec.get("created_at"))
+            if created is not None:
+                latest_candidates.append(created)
+
+            conversation_id = spec.get("conversation_id")
+            if conversation_id is not None:
+                identifier = str(conversation_id)
+                if identifier not in seen_conversations:
+                    seen_conversations.add(identifier)
+                    if conversation_base_url:
+                        link_url = f"{conversation_base_url.rstrip('/')}/{identifier}"
+                    else:
+                        link_url = f"#conversation-{identifier}"
+                    conversation_links.append({"id": identifier, "url": link_url})
+
+        section_text = _format_markdown_section(spec_type, items, conversation_base_url)
+        placeholder = MARKDOWN_SECTION_KEYS.get(spec_type)
+        if placeholder:
+            sections[placeholder] = section_text
+        elif section_text:
+            additional_section_blocks.append(f"### {spec_type}\n{section_text}")
+
+    status_counts = [
+        {"status": status.replace("_", " ").title(), "count": count}
+        for status, count in sorted(status_totals.items())
+    ]
+
+    conversation_links.sort(key=lambda item: (len(item["id"]), item["id"]))
+    latest_activity = (
+        max(latest_candidates).astimezone(timezone.utc).isoformat()
+        if latest_candidates
+        else "not_recorded"
+    )
+
+    implementation_notes = str(project_data.get("implementation_notes") or "").strip()
+    if not implementation_notes:
+        implementation_notes = "_No implementation notes provided yet._"
+
+    additional_sections = "\n\n".join(additional_section_blocks)
+
+    metadata = {
+        "project_id": project_identifier,
+        "project_created_at": project_created_at,
+        "spec_counts": spec_counts,
+        "status_counts": status_counts,
+        "conversation_links": conversation_links,
+        "latest_activity": latest_activity,
+    }
+
+    context: Dict[str, Any] = {
+        "project_name": project_name,
+        "project_description": project_description,
+        "generation_date": generated_at,
+        "spec_count": total_specs,
+        "implementation_notes": implementation_notes,
+        "additional_sections": additional_sections,
+        "metadata": metadata,
+    }
+    context.update(sections)
+    return context
+
+
+def _format_markdown_section(
+    spec_type: str,
+    items: Sequence[Mapping[str, Any]],
+    conversation_base_url: str,
+) -> str:
+    """Render a specification collection as a YAML-like Markdown block."""
+
+    if not items:
+        return f"_No {spec_type} documented yet._"
+
+    lines: List[str] = []
+    for spec in items:
+        lines.extend(_format_markdown_entry(spec, conversation_base_url))
+    return "\n".join(lines)
+
+
+def _format_markdown_entry(
+    spec: Mapping[str, Any], conversation_base_url: str
+) -> List[str]:
+    """Create a structured bullet list representation for a specification."""
+
+    title = str(spec.get("title") or "Untitled").strip() or "Untitled"
+    status = str(spec.get("status") or "pending").strip() or "pending"
+    status_label = status.replace("_", " ").title()
+
+    entry: List[str] = [f"- title: {json.dumps(title)}", f"  status: {json.dumps(status_label)}"]
+
+    spec_id = spec.get("id")
+    if spec_id is not None:
+        entry.append(f"  specification_id: {json.dumps(str(spec_id))}")
+
+    conversation_id = spec.get("conversation_id")
+    if conversation_id is not None:
+        identifier = str(conversation_id)
+        entry.append(f"  conversation_id: {json.dumps(identifier)}")
+        if conversation_base_url:
+            url = f"{conversation_base_url.rstrip('/')}/{identifier}"
+        else:
+            url = f"#conversation-{identifier}"
+        entry.append(f"  conversation_url: {json.dumps(url)}")
+
+    created = _parse_datetime(spec.get("created_at"))
+    if created is not None:
+        entry.append(f"  captured_at: {json.dumps(created.astimezone(timezone.utc).isoformat())}")
+
+    body = str(spec.get("content") or "").strip()
+    if body:
+        entry.append("  details: |")
+        for line in body.splitlines():
+            entry.append(f"    {line}")
+    else:
+        entry.append("  details: _No additional narrative provided._")
+
+    return entry
+
+
+def generate_export_html(
+    project_data: Mapping[str, Any],
+    specifications: Sequence[Mapping[str, Any]],
+) -> str:
+    """Generate an HTML report for a project and its specifications.
+
+    Args:
+        project_data: Metadata describing the project (name, description, etc.).
+        specifications: Collection of specification records to include.
+
+    Returns:
+        Rendered HTML string ready for download.
+
+    Raises:
+        ValueError: When the HTML template configuration is missing.
+    """
+
+    html_template_meta = EXPORT_TEMPLATES.get("html")
+    if not html_template_meta:
+        raise ValueError("HTML export template is not configured.")
+
+    template_path = Path(html_template_meta["path"])
+    if not template_path.is_absolute():
+        template_path = BASE_DIR / template_path
+
+    context = _prepare_html_export_context(project_data, specifications)
+    context["generated_at"] = get_current_timestamp()
+
+    return _render_template(template_path, context)
+
+
+def generate_export_markdown(
+    project_data: Mapping[str, Any],
+    specifications: Sequence[Mapping[str, Any]],
+) -> str:
+    """Generate a Markdown report mirroring the HTML export."""
+
+    md_template_meta = EXPORT_TEMPLATES.get("markdown")
+    if not md_template_meta:
+        raise ValueError("Markdown export template is not configured.")
+
+    template_path = Path(md_template_meta["path"])
+    if not template_path.is_absolute():
+        template_path = BASE_DIR / template_path
+
+    generated_at = get_current_timestamp()
+    context = _build_markdown_context(project_data, specifications, generated_at)
+    return _render_template(template_path, context)
+
+
+# ---------------------------------------------------------------------------
+# Security and auditing helpers
+# ---------------------------------------------------------------------------
+
+def sanitize_input(text: Optional[str]) -> str:
+    """Escape potentially dangerous user input before rendering.
+
+    This helper strips leading/trailing whitespace, normalises line endings, and
+    escapes HTML-sensitive characters.  It does **not** attempt to remove
+    Markdown formatting or SQL injection vectors; those concerns should be
+    handled by parameterised queries and additional context-specific checks.
+    """
+
+    if text is None:
+        return ""
+
+    cleaned = text.replace("\r\n", "\n").replace("\r", "\n").strip()
+    return html.escape(cleaned)
+
+
+def log_user_action(action: str, details: Optional[Mapping[str, Any]] = None) -> None:
+    """Record high-level user events to aid debugging and auditing.
+
+    Args:
+        action: Short description of the operation (e.g. ``"create_project"``).
+        details: Optional mapping of additional metadata for structured logs.
+    """
+
+    if not action:
+        raise ValueError("Action description must be provided for logging.")
+
+    if details is None:
+        details = {}
+
+    LOGGER.info("User action: %s | Details: %s", action, details)
+
+
+# ---------------------------------------------------------------------------
+# Time helpers
+# ---------------------------------------------------------------------------
+
+def get_current_timestamp() -> str:
+    """Return the current UTC timestamp in ISO 8601 format."""
+
+    return datetime.now(timezone.utc).isoformat()
+
+
+# ---------------------------------------------------------------------------
+# Analytics helpers
+# ---------------------------------------------------------------------------
+
+def calculate_project_stats(project_id: int) -> Dict[str, Any]:
+    """Compute aggregate metrics for a single project.
+
+    The resulting dictionary includes counts of conversations, messages, pending
+    specifications, approved specifications, and the timestamp of the most
+    recent activity.  These metrics power dashboards or can be surfaced in the
+    "Specifications" tab to give users a quick overview of project health.
+    """
+
+    if not isinstance(project_id, int) or project_id <= 0:
+        raise ValueError("project_id must be a positive integer.")
+
+    stats = {
+        "total_conversations": 0,
+        "total_messages": 0,
+        "pending_specifications": 0,
+        "approved_specifications": 0,
+        "last_activity": None,
+    }
+
+    try:
+        with sqlite3.connect(DATABASE_PATH) as conn:
+            conn.row_factory = sqlite3.Row
+            cursor = conn.cursor()
+
+            cursor.execute(
+                "SELECT COUNT(*) AS count FROM conversations WHERE project_id = ?",
+                (project_id,),
+            )
+            stats["total_conversations"] = cursor.fetchone()["count"]
+
+            cursor.execute(
+                """
+                SELECT COUNT(*) AS count
+                FROM messages m
+                JOIN conversations c ON c.id = m.conversation_id
+                WHERE c.project_id = ?
+                """,
+                (project_id,),
+            )
+            stats["total_messages"] = cursor.fetchone()["count"]
+
+            cursor.execute(
+                "SELECT COUNT(*) AS count FROM specifications WHERE project_id = ? AND status = 'pending'",
+                (project_id,),
+            )
+            stats["pending_specifications"] = cursor.fetchone()["count"]
+
+            cursor.execute(
+                "SELECT COUNT(*) AS count FROM specifications WHERE project_id = ? AND status = 'approved'",
+                (project_id,),
+            )
+            stats["approved_specifications"] = cursor.fetchone()["count"]
+
+            cursor.execute(
+                """
+                SELECT MAX(ts) AS last_activity
+                FROM (
+                    SELECT MAX(created_at) AS ts FROM conversations WHERE project_id = ?
+                    UNION ALL
+                    SELECT MAX(timestamp) AS ts FROM messages m JOIN conversations c ON c.id = m.conversation_id WHERE c.project_id = ?
+                    UNION ALL
+                    SELECT MAX(created_at) AS ts FROM specifications WHERE project_id = ?
+                )
+                """,
+                (project_id, project_id, project_id),
+            )
+            row = cursor.fetchone()
+            stats["last_activity"] = row["last_activity"] if row else None
+    except sqlite3.DatabaseError as error:
+        LOGGER.exception("Failed to calculate stats for project %s: %s", project_id, error)
+        raise
+
+    return stats
+
+
+__all__ = [
+    "validate_api_key",
+    "format_prompt",
+    "format_conversation_history",
+    "render_export",
+    "generate_export_html",
+    "generate_export_markdown",
+    "sanitize_input",
+    "log_user_action",
+    "get_current_timestamp",
+    "calculate_project_stats",
+]