Add HF trace storage, admin controls, and Spaces deployment

- Upload traces as JSON to a HF dataset repo after each question
- Add Traces tab with session-scoped view (admin URL param for full history)
- Replace Gradio login with inline token field
- Decouple chat history from agent loop (display only)
- Add huggingface-hub dependency and requirements.txt for HF Spaces
- Add .claudeignore to exclude .env files

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claudeignore

@@ -0,0 +1,3 @@
+.env
+.env.local
+.env.*.local

.env.example

@@ -11,4 +11,9 @@ E2B_API_KEY=your-e2b-api-key
 
 # Web app authentication
 LH_ACCESS_TOKEN=your-secret-token
+# LH_ADMIN_TOKEN=your-admin-token
 # LH_MAX_SESSION_COST=0.50
+
+# Hugging Face trace storage (optional)
+# HF_TOKEN=your-hf-write-token
+# HF_TRACES_REPO=your-username/document-explorer-traces

README.md

@@ -7,6 +7,7 @@ sdk: gradio
 sdk_version: "6.9.0"
 app_file: app.py
 pinned: false
+python_version: "3.12"
 ---
 
 # Document Explorer

app.py

@@ -9,15 +9,18 @@ Uses E2B sandboxes for code execution (no Docker required).
 
 from __future__ import annotations
 
+import json
 import os
 import tempfile
 import time
 from dataclasses import asdict
+from datetime import datetime, timezone
 from pathlib import Path
 
 import gradio as gr
 import litellm
 from dotenv import load_dotenv
+from huggingface_hub import HfApi
 
 from llm_harness.agent import run_agent_loop
 from llm_harness.prompt import build_system_prompt
@@ -32,11 +35,64 @@ litellm.suppress_debug_info = True
 
 MODEL = os.environ.get("LH_MODEL", "")
 ACCESS_TOKEN = os.environ.get("LH_ACCESS_TOKEN", "")
+ADMIN_TOKEN = os.environ.get("LH_ADMIN_TOKEN", "")
 MAX_SESSION_COST = float(os.environ.get("LH_MAX_SESSION_COST", "0.50"))
+HF_TRACES_REPO = os.environ.get("HF_TRACES_REPO", "")
+HF_TOKEN = os.environ.get("HF_TOKEN", "")
 
+hf_api = HfApi(token=HF_TOKEN) if HF_TOKEN else None
 
-def authenticate(username: str, password: str) -> bool:
-    return password == ACCESS_TOKEN
+
+def _slugify(text: str, max_len: int = 50) -> str:
+    slug = text.lower().replace(" ", "-")
+    slug = "".join(c for c in slug if c.isalnum() or c == "-")
+    return slug[:max_len].rstrip("-")
+
+
+def upload_trace(result: dict) -> str | None:
+    if not hf_api or not HF_TRACES_REPO:
+        return None
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S-%f")
+    question_slug = _slugify(result.get("question", ""))
+    filename = f"{timestamp}_{question_slug}.json" if question_slug else f"{timestamp}.json"
+    content = json.dumps(result, indent=2, default=str).encode()
+    try:
+        hf_api.upload_file(
+            path_or_fileobj=content,
+            path_in_repo=filename,
+            repo_id=HF_TRACES_REPO,
+            repo_type="dataset",
+        )
+        return filename
+    except Exception as exc:
+        print(f"WARNING: trace upload failed: {exc}")
+        return None
+
+
+def list_traces() -> list[str]:
+    if not hf_api or not HF_TRACES_REPO:
+        return []
+    try:
+        files = hf_api.list_repo_files(HF_TRACES_REPO, repo_type="dataset")
+        traces = sorted(
+            [f for f in files if f.endswith(".json")],
+            reverse=True,
+        )
+        return traces
+    except Exception:
+        return []
+
+
+def fetch_trace(filename: str) -> dict | None:
+    if not hf_api or not HF_TRACES_REPO or not filename:
+        return None
+    try:
+        path = hf_api.hf_hub_download(
+            HF_TRACES_REPO, filename, repo_type="dataset"
+        )
+        return json.loads(Path(path).read_text())
+    except Exception:
+        return None
 
 
 def save_uploaded_files(files: list[str]) -> Path:
@@ -67,30 +123,27 @@ def format_stats(trace: object) -> str:
 
 def chat(
     message: str,
-    history: list[dict],
     files: list[str] | None,
     workspace_path: str,
     scratch_path: str,
     session_cost: float,
+    token: str = "",
 ):
+    empty = ("", "", workspace_path, scratch_path, session_cost, None)
+
+    if ACCESS_TOKEN and token != ACCESS_TOKEN:
+        yield ("Invalid access token.", *empty[1:])
+        return
+
     if not MODEL:
-        yield (
-            "Error: LH_MODEL not set.",
-            "",
-            workspace_path,
-            scratch_path,
-            session_cost,
-        )
+        yield ("Error: LH_MODEL not set.", *empty[1:])
         return
 
     if session_cost >= MAX_SESSION_COST:
         yield (
             f"Session cost limit reached (${session_cost:.2f} / "
             f"${MAX_SESSION_COST:.2f}). Start a new session.",
-            "",
-            workspace_path,
-            scratch_path,
-            session_cost,
+            *empty[1:],
         )
         return
 
@@ -105,11 +158,11 @@ def chat(
         scratch_path = tempfile.mkdtemp(prefix="lh-scratch-")
     scratch_dir = Path(scratch_path)
 
-    # Build messages from Gradio history
     system_prompt = build_system_prompt(base_prompt="", workspace=workspace)
-    messages: list[Message] = [{"role": "system", "content": system_prompt}]
-    messages.extend({"role": e["role"], "content": e["content"]} for e in history)
-    messages.append({"role": "user", "content": message})
+    messages: list[Message] = [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": message},
+    ]
 
     # Run agent loop with E2B sandbox
     start = time.monotonic()
@@ -129,7 +182,7 @@ def chat(
             if isinstance(event, ToolCallEvent):
                 tool_call_count += 1
                 status = f"*Exploring documents ({tool_call_count} tool calls)...*"
-                yield status, "", workspace_path, scratch_path, session_cost
+                yield status, "", workspace_path, scratch_path, session_cost, None
             elif isinstance(event, ToolResultEvent):
                 continue
             else:
@@ -142,6 +195,7 @@ def chat(
             workspace_path,
             scratch_path,
             session_cost,
+            None,
         )
         return
 
@@ -149,10 +203,9 @@ def chat(
     trace.wall_time_s = round(time.monotonic() - start, 2)
     answer = trace.answer or "(no answer)"
     stats = format_stats(trace)
-    trace_html = render_trace(
-        {"question": message, "passed": True, "assertions": {}, "trace": asdict(trace)},
-        max_chars=2000,
-    )
+    result = {"question": message, "passed": True, "assertions": {}, "trace": asdict(trace)}
+    trace_filename = upload_trace(result)
+    trace_html = render_trace(result, max_chars=2000)
 
     yield (
         f"{answer}\n\n---\n{stats}",
@@ -160,74 +213,146 @@ def chat(
         workspace_path,
         scratch_path,
         session_cost,
+        trace_filename,
     )
 
 
 def build_app() -> gr.Blocks:
     with gr.Blocks(title="Document Explorer", theme=gr.themes.Soft()) as demo:
-        gr.Markdown(
-            "# Document Explorer\n"
-            "Upload text or CSV files, then ask questions. "
-            "The model explores your documents by writing and running Python code."
-        )
-
-        workspace_state = gr.State("")
-        scratch_state = gr.State("")
-        cost_state = gr.State(0.0)
-
-        with gr.Accordion("Upload documents", open=True):
-            file_upload = gr.File(
-                label="Text, CSV, Markdown, or JSON files",
-                file_count="multiple",
-                file_types=[".txt", ".csv", ".md", ".json"],
-            )
-
-        chatbot = gr.Chatbot(height=500)
-        msg = gr.Textbox(
-            placeholder="Ask a question about your documents...",
-            label="",
-            show_label=False,
-        )
-
-        with gr.Accordion("Trace", open=False, visible=False) as trace_accordion:
-            trace_display = gr.HTML("")
-
-        def respond(
-            message, history, files, workspace_path, scratch_path, session_cost
-        ):
-            history = history or []
-            history.append({"role": "user", "content": message})
-
-            for response, trace_html, wp, sp, sc in chat(
-                message, history[:-1], files, workspace_path, scratch_path, session_cost
-            ):
-                history_with_response = [
-                    *history,
-                    {"role": "assistant", "content": response},
-                ]
-                visible = gr.update(visible=bool(trace_html))
-                yield history_with_response, "", trace_html, visible, wp, sp, sc
-
-        msg.submit(
-            respond,
-            inputs=[
-                msg,
-                chatbot,
-                file_upload,
-                workspace_state,
-                scratch_state,
-                cost_state,
-            ],
-            outputs=[
-                chatbot,
-                msg,
-                trace_display,
-                trace_accordion,
-                workspace_state,
-                scratch_state,
-                cost_state,
-            ],
-        )
+        gr.Markdown("# Document Explorer")
+
+        with gr.Tabs():
+            with gr.Tab("Chat"):
+                gr.Markdown(
+                    "Upload text or CSV files, then ask questions. "
+                    "The model explores your documents by writing and running Python code."
+                )
+
+                workspace_state = gr.State("")
+                scratch_state = gr.State("")
+                cost_state = gr.State(0.0)
+                session_traces_state = gr.State([])  # filenames uploaded this session
+
+                with gr.Row():
+                    token_input = gr.Textbox(
+                        placeholder="Access token",
+                        label="Access Token",
+                        type="password",
+                        scale=1,
+                    )
+
+                with gr.Accordion("Upload documents", open=True):
+                    file_upload = gr.File(
+                        label="Text, CSV, Markdown, or JSON files",
+                        file_count="multiple",
+                        file_types=[".txt", ".csv", ".md", ".json"],
+                    )
+
+                chatbot = gr.Chatbot(height=500)
+                msg = gr.Textbox(
+                    placeholder="Ask a question about your documents...",
+                    label="",
+                    show_label=False,
+                )
+
+                with gr.Accordion("Trace", open=False, visible=False) as trace_accordion:
+                    trace_display = gr.HTML("")
+
+                def respond(
+                    message, history, files, workspace_path, scratch_path,
+                    session_cost, session_traces, token,
+                ):
+                    history = history or []
+                    history.append({"role": "user", "content": message})
+
+                    for response, trace_html, wp, sp, sc, trace_file in chat(
+                        message, files, workspace_path, scratch_path, session_cost, token
+                    ):
+                        if trace_file:
+                            session_traces = [*session_traces, trace_file]
+                        history_with_response = [
+                            *history,
+                            {"role": "assistant", "content": response},
+                        ]
+                        accordion = gr.Accordion(visible=bool(trace_html))
+                        yield (
+                            history_with_response, "", trace_html, accordion,
+                            wp, sp, sc, session_traces,
+                        )
+
+                msg.submit(
+                    respond,
+                    inputs=[
+                        msg,
+                        chatbot,
+                        file_upload,
+                        workspace_state,
+                        scratch_state,
+                        cost_state,
+                        session_traces_state,
+                        token_input,
+                    ],
+                    outputs=[
+                        chatbot,
+                        msg,
+                        trace_display,
+                        trace_accordion,
+                        workspace_state,
+                        scratch_state,
+                        cost_state,
+                        session_traces_state,
+                    ],
+                )
+
+            with gr.Tab("Traces") as traces_tab:
+                admin_state = gr.State(False)
+                trace_dropdown = gr.Dropdown(
+                    choices=[],
+                    label="Select trace",
+                )
+                refresh_btn = gr.Button("Refresh")
+                trace_viewer = gr.HTML("")
+
+                def check_admin(request: gr.Request):
+                    token = request.query_params.get("admin", "")
+                    return ADMIN_TOKEN and token == ADMIN_TOKEN
+
+                def show_trace(filename):
+                    result = fetch_trace(filename)
+                    if not result:
+                        return ""
+                    return render_trace(result, max_chars=5000)
+
+                def refresh_traces(session_traces, is_admin):
+                    if is_admin:
+                        filenames = list_traces()
+                    else:
+                        filenames = sorted(session_traces, reverse=True)
+                    return gr.Dropdown(
+                        choices=filenames,
+                        value=filenames[0] if filenames else None,
+                    )
+
+                demo.load(
+                    check_admin,
+                    outputs=[admin_state],
+                )
+
+                trace_dropdown.change(
+                    show_trace,
+                    inputs=[trace_dropdown],
+                    outputs=[trace_viewer],
+                )
+                refresh_btn.click(
+                    refresh_traces,
+                    inputs=[session_traces_state, admin_state],
+                    outputs=[trace_dropdown],
+                )
+                traces_tab.select(
+                    refresh_traces,
+                    inputs=[session_traces_state, admin_state],
+                    outputs=[trace_dropdown],
+                )
 
     return demo
 
@@ -237,4 +362,4 @@ if __name__ == "__main__":
         print("WARNING: LH_ACCESS_TOKEN not set — app is unprotected")
 
     app = build_app()
-    app.launch(auth=authenticate if ACCESS_TOKEN else None)
+    app.launch()

pyproject.toml

@@ -11,6 +11,7 @@ dependencies = [
     "a-simple-llm-harness",
     "e2b-code-interpreter>=2.5",
     "gradio>=5.0",
+    "huggingface-hub",
     "python-dotenv",
 ]
 

requirements.txt

@@ -0,0 +1,269 @@
+# This file was autogenerated by uv via the following command:
+#    uv export --format requirements-txt --no-hashes
+a-simple-llm-harness @ git+https://github.com/chuckfinca/a-simple-llm-harness.git@a67e2cc8dcf320d5df765c44fbee282ba1aa5331
+    # via document-explorer
+aiofiles==24.1.0
+    # via gradio
+aiohappyeyeballs==2.6.1
+    # via aiohttp
+aiohttp==3.13.3
+    # via litellm
+aiosignal==1.4.0
+    # via aiohttp
+annotated-doc==0.0.4
+    # via
+    #   fastapi
+    #   typer
+annotated-types==0.7.0
+    # via pydantic
+anyio==4.12.1
+    # via
+    #   gradio
+    #   httpx
+    #   openai
+    #   starlette
+attrs==26.1.0
+    # via
+    #   aiohttp
+    #   e2b
+    #   e2b-code-interpreter
+    #   jsonschema
+    #   referencing
+audioop-lts==0.2.2 ; python_full_version >= '3.13'
+    # via gradio
+bracex==2.6
+    # via wcmatch
+brotli==1.2.0
+    # via gradio
+certifi==2026.2.25
+    # via
+    #   httpcore
+    #   httpx
+    #   requests
+charset-normalizer==3.4.6
+    # via requests
+click==8.3.1
+    # via
+    #   litellm
+    #   typer
+    #   uvicorn
+colorama==0.4.6 ; sys_platform == 'win32'
+    # via
+    #   click
+    #   tqdm
+distro==1.9.0
+    # via openai
+dockerfile-parse==2.0.1
+    # via e2b
+e2b==2.15.3
+    # via e2b-code-interpreter
+e2b-code-interpreter==2.5.0
+    # via document-explorer
+fastapi==0.135.2
+    # via gradio
+fastuuid==0.14.0
+    # via litellm
+ffmpy==1.0.0
+    # via gradio
+filelock==3.25.2
+    # via huggingface-hub
+frozenlist==1.8.0
+    # via
+    #   aiohttp
+    #   aiosignal
+fsspec==2026.2.0
+    # via
+    #   gradio-client
+    #   huggingface-hub
+gradio==6.9.0
+    # via document-explorer
+gradio-client==2.3.0
+    # via gradio
+groovy==0.1.2
+    # via gradio
+h11==0.16.0
+    # via
+    #   httpcore
+    #   uvicorn
+hf-xet==1.4.2 ; platform_machine == 'AMD64' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'
+    # via huggingface-hub
+httpcore==1.0.9
+    # via
+    #   e2b
+    #   httpx
+httpx==0.28.1
+    # via
+    #   e2b
+    #   e2b-code-interpreter
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   litellm
+    #   openai
+    #   safehttpx
+huggingface-hub==1.7.2
+    # via
+    #   document-explorer
+    #   gradio
+    #   gradio-client
+    #   tokenizers
+idna==3.11
+    # via
+    #   anyio
+    #   httpx
+    #   requests
+    #   yarl
+importlib-metadata==9.0.0
+    # via litellm
+jinja2==3.1.6
+    # via
+    #   gradio
+    #   litellm
+jiter==0.13.0
+    # via openai
+jsonschema==4.26.0
+    # via litellm
+jsonschema-specifications==2025.9.1
+    # via jsonschema
+litellm==1.82.6
+    # via a-simple-llm-harness
+markdown-it-py==4.0.0
+    # via rich
+markupsafe==3.0.3
+    # via
+    #   gradio
+    #   jinja2
+mdurl==0.1.2
+    # via markdown-it-py
+multidict==6.7.1
+    # via
+    #   aiohttp
+    #   yarl
+numpy==2.4.3
+    # via
+    #   gradio
+    #   pandas
+openai==2.29.0
+    # via litellm
+orjson==3.11.7
+    # via gradio
+packaging==26.0
+    # via
+    #   e2b
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+pandas==3.0.1
+    # via gradio
+pillow==12.1.1
+    # via gradio
+propcache==0.4.1
+    # via
+    #   aiohttp
+    #   yarl
+protobuf==7.34.1
+    # via e2b
+pydantic==2.12.5
+    # via
+    #   fastapi
+    #   gradio
+    #   litellm
+    #   openai
+pydantic-core==2.41.5
+    # via pydantic
+pydub==0.25.1
+    # via gradio
+pygments==2.19.2
+    # via rich
+python-dateutil==2.9.0.post0
+    # via
+    #   e2b
+    #   pandas
+python-dotenv==1.2.2
+    # via
+    #   document-explorer
+    #   litellm
+python-multipart==0.0.22
+    # via gradio
+pytz==2026.1.post1
+    # via gradio
+pyyaml==6.0.3
+    # via
+    #   gradio
+    #   huggingface-hub
+referencing==0.37.0
+    # via
+    #   jsonschema
+    #   jsonschema-specifications
+regex==2026.2.28
+    # via tiktoken
+requests==2.32.5
+    # via tiktoken
+rich==14.3.3
+    # via
+    #   a-simple-llm-harness
+    #   e2b
+    #   typer
+rpds-py==0.30.0
+    # via
+    #   jsonschema
+    #   referencing
+safehttpx==0.1.7
+    # via gradio
+semantic-version==2.10.0
+    # via gradio
+shellingham==1.5.4
+    # via typer
+six==1.17.0
+    # via python-dateutil
+sniffio==1.3.1
+    # via openai
+starlette==0.52.1
+    # via
+    #   fastapi
+    #   gradio
+tiktoken==0.12.0
+    # via litellm
+tokenizers==0.22.2
+    # via litellm
+tomlkit==0.13.3
+    # via gradio
+tqdm==4.67.3
+    # via
+    #   huggingface-hub
+    #   openai
+typer==0.24.1
+    # via
+    #   gradio
+    #   huggingface-hub
+typing-extensions==4.15.0
+    # via
+    #   aiosignal
+    #   anyio
+    #   e2b
+    #   fastapi
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   openai
+    #   pydantic
+    #   pydantic-core
+    #   referencing
+    #   starlette
+    #   typing-inspection
+typing-inspection==0.4.2
+    # via
+    #   fastapi
+    #   pydantic
+tzdata==2025.3 ; sys_platform == 'emscripten' or sys_platform == 'win32'
+    # via pandas
+urllib3==2.6.3
+    # via requests
+uvicorn==0.42.0
+    # via gradio
+wcmatch==10.1
+    # via e2b
+yarl==1.23.0
+    # via aiohttp
+zipp==3.23.0
+    # via importlib-metadata

uv.lock

@@ -410,6 +410,7 @@ dependencies = [
     { name = "a-simple-llm-harness" },
     { name = "e2b-code-interpreter" },
     { name = "gradio" },
+    { name = "huggingface-hub" },
     { name = "python-dotenv" },
 ]
 
@@ -418,6 +419,7 @@ requires-dist = [
     { name = "a-simple-llm-harness", git = "https://github.com/chuckfinca/a-simple-llm-harness.git" },
     { name = "e2b-code-interpreter", specifier = ">=2.5" },
     { name = "gradio", specifier = ">=5.0" },
+    { name = "huggingface-hub" },
     { name = "python-dotenv" },
 ]