Agent.md

# Hugging Face Deployment Guide

1. Deployment Configuration
Target Space
Profile: GraziePrego
Space: deepresearch
Full Identifier: GraziePrego/deepresearch
Frontend Port: 7860 (mandatory for all Hugging Face Spaces)

Deployment Method
Choose the correct SDK based on the app type based on the codebase language:
Gradio SDK — for Gradio applications
Streamlit SDK — for Streamlit applications
Docker SDK — for all other applications (recommended default for flexibility)

HF Token
The environment variable `<HF_TOKEN>` will always be provided at execution time.
Never hardcode the token. Always read it from the environment.
All monitoring and log‑streaming commands rely on `<HF_TOKEN>`.

Required Files
Dockerfile (or app.py for Gradio/Streamlit SDKs)
README.md with Hugging Face YAML frontmatter:
---
title: deepresearch
sdk: docker
app_port: 7860
---
.hfignore to exclude unnecessary files
This Agent.md file (must be committed before deployment)

2. API Exposure and Documentation
Mandatory Endpoints
Every deployment must expose:

/health
Returns HTTP 200 when the app is ready.
Required for Hugging Face to transition the Space from starting → running.

/api-docs
Documents all available API endpoints.
Must be reachable at:
https://GraziePrego-deepresearch.hf.space/api-docs

Functional Endpoints
Document each endpoint here. For every endpoint, include:

### /health
- Method: GET
- Purpose: Returns HTTP 200 when the app is ready. Required for Hugging Face to transition the Space from starting → running.
- Request: {}
- Response: { "status": "ok" }

### /api-docs
- Method: GET
- Purpose: Documents all available API endpoints.
- Request: {}
- Response: { "endpoints": [...] }

3. Deployment Workflow
Precondition: Use the huggingface hub cli hf to check that the space is empty of files nd delete any which are still in there and not belonging to the project to be uploaded

Standard Deployment Command
After any code change, run:
hf upload GraziePrego/deepresearch --repo-type=space

Scan build and run logs # Get build logs (SSE) curl -N
-H "Authorization: Bearer <HF_TOKEN>"
"https://huggingface.co/api/spaces/GraziePrego/deepresearch/logs/build"

Get run logs (SSE) once the build logs succeed
curl -N
-H "Authorization: Bearer <HF_TOKEN>"
"https://huggingface.co/api/spaces/GraziePrego/deepresearch/logs/run"

---

## OpenAI Compatible Configuration (Blablador)

If you are using a custom OpenAI-Compatible API provider (like `api.helmholtz-blablador.fz-juelich.de`), you must ensure that your browser doesn't block the request. Custom API providers frequently block direct cross-origin browser fetches (CORS restrictions). Therefore:

1. Use **Server Proxy** mode in the Settings box of your App.
2. In Hugging Face Spaces, you should configure your connection settings natively using **Hugging Face Secrets**. Do **not** hardcode them.

Set the following Secrets in the settings of your Space:

- `BASE_URL`: For example, `https://api.helmholtz-blablador.fz-juelich.de/v1`
- `BLABLADOR_API_KEY`: Your authentication token

When the frontend performs an operation (like "Start thinking"), it routes through the Server Proxy (`/api/ai/openaicompatible/v1/...`). Our proxy explicitly reads these `BASE_URL` and `BLABLADOR_API_KEY` secrets to establish the connection properly and automatically appends the token to the header!

### About the `Access Password` (ACCESS_PASSWORD secret)

If you configure an `ACCESS_PASSWORD` Hugging Face Secret, your application enters a protected mode where only users who know this password can perform searches or stream text.
- If you set it in your Space Secrets, **you must also enter the exact same password in the app's Settings UI** for requests to work.
- If you do **not** set an `ACCESS_PASSWORD` secret, the application remains completely open to the public and relies purely on your stored `BLABLADOR_API_KEY`.