build_space_artifact.py

#!/usr/bin/env python3
"""Build a versioned Hugging Face Space artifact for TinyModel (Universal Brain chat UI).

Copies the in-repo chat stack (`universal_brain_chat` + dependencies) into a flat Space layout:
  <output>/
    app.py                 # HF entrypoint
    requirements.txt
    README.md
    scripts/*.py
    texts/rag_faq_corpus.md
"""

from __future__ import annotations

import argparse
import json
import shutil
from pathlib import Path

_PROG = "build_space_artifact"

SCRIPT_FILES = (
    "universal_brain_chat.py",
    "eval_report_routing.py",
    "google_cse_client.py",
    "horizon2_core.py",
    "horizon3_store.py",
    "nl_controls.py",
    "rag_faq_smoke.py",
    "tinymodel_runtime.py",
)


def build_parser() -> argparse.ArgumentParser:
    epilog = (
        "Examples:\n"
        "  python scripts/build_space_artifact.py --namespace HyperlinksSpace --version 1 "
        "--output-dir .tmp/TinyModel1Space-bundle\n"
        "  python scripts/build_space_artifact.py --namespace MyOrg --version 2 --output-dir .tmp/space2 "
        "--model-id MyOrg/TinyModel2"
    )
    p = argparse.ArgumentParser(
        prog=_PROG,
        description=(
            "Generate Space files for TinyModel{version}Space (Universal Brain chat). "
            "Copies the in-repo chat stack into a flat layout under --output-dir."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=epilog,
    )
    p.add_argument("--namespace", required=True, help="HF org/user namespace")
    p.add_argument("--version", required=True, help="Artifact version number")
    p.add_argument("--output-dir", required=True, help="Output directory path")
    p.add_argument(
        "--model-id",
        required=False,
        default="",
        help="HF classifier model repo id for --encoder (default: {namespace}/TinyModel{version}).",
    )
    p.add_argument(
        "--github-repo-url",
        default="https://github.com/HyperlinksSpace/TinyModel",
        help="GitHub repo URL shown in the Space UI.",
    )
    return p


def parse_args() -> argparse.Namespace:
    return build_parser().parse_args()


def main() -> None:
    args = parse_args()
    version = str(args.version).strip()
    if not version.isdigit() or int(version) < 1:
        raise ValueError("Version must be a positive integer, e.g. 1 or 2.")

    model_name = f"TinyModel{version}"
    space_name = f"{model_name}Space"
    model_id = args.model_id.strip() or f"{args.namespace}/{model_name}"
    github_repo_url = args.github_repo_url.strip()
    public_app_url = f"https://{args.namespace.lower()}-{space_name.lower()}.hf.space"
    model_hub_url = f"https://huggingface.co/{model_id}"
    model_id_literal = json.dumps(model_id)

    repo_root = Path(__file__).resolve().parent.parent
    scripts_src = repo_root / "scripts"
    corpus_src = repo_root / "texts" / "rag_faq_corpus.md"
    if not corpus_src.is_file():
        raise FileNotFoundError(f"Missing FAQ corpus: {corpus_src}")

    output_dir = Path(args.output_dir)
    output_dir.mkdir(parents=True, exist_ok=True)
    scripts_dst = output_dir / "scripts"
    scripts_dst.mkdir(parents=True, exist_ok=True)
    texts_dst = output_dir / "texts"
    texts_dst.mkdir(parents=True, exist_ok=True)

    for name in SCRIPT_FILES:
        src = scripts_src / name
        if not src.is_file():
            raise FileNotFoundError(f"Missing script required for Space: {src}")
        shutil.copy2(src, scripts_dst / name)
    shutil.copy2(corpus_src, texts_dst / "rag_faq_corpus.md")

    app_py = f"""# Hugging Face Space entry — Universal Brain chat (generated by build_space_artifact.py).
from __future__ import annotations

import os
import sys
from pathlib import Path

_ROOT = Path(__file__).resolve().parent
_SCRIPTS = _ROOT / "scripts"
sys.path.insert(0, str(_SCRIPTS))
os.chdir(_ROOT)

# Loopback probes (Gradio / httpx); harmless on Space.
os.environ.setdefault("NO_PROXY", "localhost,127.0.0.1,::1")

SPACE_ENCODER_ID = {model_id_literal}
PUBLIC_APP_URL = {json.dumps(public_app_url)}
MODEL_HUB_URL = {json.dumps(model_hub_url)}
GITHUB_REPO_URL = {json.dumps(github_repo_url)}
SPACE_NAME = {json.dumps(space_name)}


def main() -> None:
    port = int(os.environ.get("PORT", "7860"))
    argv = [
        "universal_brain_chat.py",
        "--host",
        "0.0.0.0",
        "--port",
        str(port),
        "--encoder",
        SPACE_ENCODER_ID,
    ]
    gen = os.environ.get("HORIZON2_MODEL", "").strip()
    if gen:
        argv.extend(["--model", gen])
    sys.argv = argv
    from universal_brain_chat import main as ub_main

    ub_main()


if __name__ == "__main__":
    main()
"""

    requirements = """gradio>=5.49.0,<6
transformers>=4.40.0,<5
torch>=2.2.0
accelerate>=0.26.0
safetensors>=0.4.0
"""

    caps_doc_url = f"{github_repo_url}/blob/main/texts/universal-brain-capabilities.md"
    readme = f"""---
title: {space_name}
emoji: 🤗
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
---

# {space_name}

**Universal Brain** is a **text** chat demo: plain-language **routing**, a small **instruct LM** (default **SmolLM2-360M-Instruct**, override **`HORIZON2_MODEL`**), **TinyModel1** encoder ([model card]({model_hub_url}) · `{model_id}`), **FAQ hybrid RAG**, **scoped SQLite memory**, optional **Google web search**, plus **40+ embedded prompt signals** detected from long messages.

**Try it:** type naturally or **`/help`** · say **Show the brain trace** · scroll below the chat to **Testing embedded prompt signals**.

| What you can do | How |
| --- | --- |
| **Chat & tools** | Summarize, rewrite, grounded Q&A, FAQ search, classify (4 topics), similarity, embeddings, nearest match, memory — via routing or **`/summarize`**, **`/retrieve`**, **`/web`**, … |
| **Web (optional)** | **`GOOGLE_CSE_API_KEY`** + **`GOOGLE_CSE_CX`** secrets → live snippets with **[Web n]** cites |
| **Memory** | Remember / list / export notes; *Start a new private session* for demo isolation |
| **Session controls** | Short phrases: *Be brief*, *Strict FAQ*, *Use bullet points*, *Reset reply style*, … (persist; see **`/help`**) |
| **Embedded signals** | Long questions: *pros and cons*, *in Spanish*, *code only*, *rank options*, *Mermaid diagram*, *STAR format*, *don't mention X*, … → footer **`prompt_signals:`** |

Full reference: [{caps_doc_url}]({caps_doc_url}) · Repo: [{github_repo_url}]({github_repo_url}) · App: [{public_app_url}]({public_app_url})

**Not supported:** images/audio/video; guaranteed factual accuracy on hard reasoning; private multi-tenant auth on the public demo scope.

### Secrets (recommended)

- **`HF_TOKEN`** — reliable Hub downloads for generative + encoder weights.
- **`GOOGLE_CSE_API_KEY`** + **`GOOGLE_CSE_CX`** — Google Custom Search (web in chat).

### Optional environment

- **`HORIZON2_MODEL`** — generative instruct model id.
- **`NO_AUTO_WEB`** — `1` / `true` / `on` disables automatic chat→web upgrades (router + `/web` still work).

### Startup

First **CPU** boot may take several minutes (two models). Use a **GPU** Space or a smaller **`HORIZON2_MODEL`** for faster replies.
"""

    (output_dir / "app.py").write_text(app_py, encoding="utf-8")
    (output_dir / "requirements.txt").write_text(requirements, encoding="utf-8")
    (output_dir / "README.md").write_text(readme, encoding="utf-8")
    print(f"Built Universal Brain Space artifact in {output_dir}")


if __name__ == "__main__":
    main()