# Agent Deployment & Operational Guide

This codebase is configured for deployment on Hugging Face Spaces using the Docker SDK.

## 1. Deployment Configuration

### Target Space
- **Profile:** `Leon4gr45`
- **Space:** `nodepad-hypotheses`
- **Full Identifier:** `Leon4gr45/nodepad-hypotheses`
- **Frontend Port:** `7860` (mandatory for Hugging Face Spaces)

### Container & Build Setup
- **SDK:** `docker`
- **Dockerfile:** Multi-stage Docker build utilizing Next.js standalone output mode (`output: "standalone"` in `next.config.mjs`).
- **Port Mapping:** Exposes port `7860` and sets `PORT=7860` and `HOSTNAME="0.0.0.0"`.

### Environment Variables & Runtime LLM Default Configuration
All configuration variables are read dynamically from `process.env`. Key variables include:
- `NODEPAD_DATA_DIR`: Root directory for file-backed storage (default `./data`).
- `NODEPAD_STORE`: Store strategy (`file`).
- `NODEPAD_HEARTBEAT_ENABLED`: Enables automated heartbeat worker (`true`/`false`).
- `NODEPAD_HEARTBEAT_INTERVAL_SECONDS`: Heartbeat cycle interval.
- `NODEPAD_RESEARCH_ENABLED`: Enables automated background research synthesis.
- `NODEPAD_MAX_RESEARCH_TASKS_PER_HEARTBEAT`: Maximum tasks queued per heartbeat cycle.
- `NODEPAD_GITHUB_SYNC`, `NODEPAD_GITHUB_REPOSITORY`, `NODEPAD_GITHUB_TOKEN`, `NODEPAD_GITHUB_BRANCH`: Remote GitHub backup configuration.
- `NODEPAD_API_KEY`: Optional Bearer token for API authorization.

#### Hugging Face Space Runtime LLM Configuration:
- **HF Space Variables:**
  - `OPENAI_URL`: Base URL of OpenAI-compatible inference server (e.g. `https://my-openai-server.example.com/v1`).
  - `OPENAI_MODEL`: Model identifier (e.g. `gemma-3-12b`).
- **HF Space Secret:**
  - `OPENAI_API`: API key/bearer token for the endpoint.

**Crucial:**
- Never put `OPENAI_API` in a Space Variable. Always put secrets into HF Space Secrets.
- Changing `OPENAI_URL`, `OPENAI_MODEL`, or `OPENAI_API` does NOT require rebuilding the Docker container — only a standard Hugging Face Space restart is needed to pick up updated runtime environment variables.
- `OPENAI_API` is kept strictly server-side and is NEVER sent to client browsers or stored in workspace backups or brain exports.

---

## 2. Mandatory & Functional API Endpoints

### Mandatory Endpoints
- **`/health`**
  - Method: `GET`
  - Purpose: Returns HTTP 200 when container is ready (`{ "status": "ok" }`). Required for HF Space state transition (*starting* -> *running*).
- **`/api-docs`**
  - Method: `GET`
  - Purpose: Documents all functional API endpoints exposed by the server. Accessible at `https://Leon4gr45-nodepad-hypotheses.hf.space/api-docs`.

### Functional Endpoints
- **`/api/v1/llm/status`** (GET): Returns health and availability status of the default OpenAI-compatible LLM provider without exposing secrets.
- **`/api/v1/llm/test`** (POST): Authenticated test route (`NODEPAD_API_KEY` required if set) sending prompt payload to test the configured default LLM provider.
- **`/api/v1/portfolio`** (GET): Aggregate portfolio metrics across workspaces.
- **`/api/v1/workspaces`** (GET): List active workspaces.
- **`/api/v1/workspaces/:id/graph`** (GET): Query workspace spatial/knowledge graph with filters.
- **`/api/v1/workspaces/:id/context`** (GET): Context, revision, and backup state.
- **`/api/v1/workspaces/:id/evidence`** (GET, POST): Retrieve or insert evidence claims.
- **`/api/v1/workspaces/:id/hypotheses`** (GET, POST): Retrieve or construct hypothesis nodes.
- **`/api/v1/workspaces/:id/research/tasks`** (GET, POST): Query or queue research tasks.
- **`/api/v1/workspaces/:id/research/tasks/:taskId/claim`** (POST): Claim task execution lease.
- **`/api/v1/workspaces/:id/research/tasks/:taskId/results`** (POST): Submit research task results.
- **`/api/v1/workspaces/:id/brain`** (GET): Inspection state, qualification badges, and audit trail.
- **`/api/v1/workspaces/:id/events`** (GET): Domain event stream.
- **`/api/v1/workspaces/:id/events/agent`** (POST): Append agent event.
- **`/api/v1/workspaces/:id/syntheses/run`** (POST): Execute synthesis family algorithms.
- **`/api/v1/workspaces/:id/heartbeat`** (POST): Trigger manual heartbeat cycle.
- **`/api/v1/workspaces/:id/github/backup`** (POST): Trigger workspace state snapshot sync.
- **`/api/v1/workspaces/:id/github/restore`** (POST): Stage workspace restore from git ref.
- **`/api/fetch-url`** (POST): Server-side URL fetching for research and web grounding.

---

## 3. Iterative Deployment & Monitoring Workflow

### Uploading Files
To deploy updates to the target space:
```bash
python3 -c "
from huggingface_hub import HfApi
api = HfApi(token='<HF_TOKEN>')
api.upload_folder(
    folder_path='.',
    repo_id='Leon4gr45/nodepad-hypotheses',
    repo_type='space',
    ignore_patterns=['node_modules/**', '.next/**', '.git/**']
)
"
```

### Log Monitoring
Stream build logs:
```bash
curl -N -H "Authorization: Bearer <HF_TOKEN>" "https://huggingface.co/api/spaces/Leon4gr45/nodepad-hypotheses/logs/build"
```

Stream runtime logs:
```bash
curl -N -H "Authorization: Bearer <HF_TOKEN>" "https://huggingface.co/api/spaces/Leon4gr45/nodepad-hypotheses/logs/run"
```

### Best Practices & Deployment Tricks
1. **Next.js Standalone Mode:** Always ensure `output: "standalone"` is set in `next.config.mjs` when building inside Docker to minimize image layer size.
2. **Port Binding:** Hugging Face Spaces require binding to `0.0.0.0:7860`.
3. **Storage Persistence:** Next.js standalone runner defaults to local memory/filesystem storage (`NODEPAD_DATA_DIR`). For persistent cross-restart state, configure GitHub backup environment variables (`NODEPAD_GITHUB_SYNC=true`, `NODEPAD_GITHUB_TOKEN`, etc.).