Create README.md

README.md

@@ -1,12 +1,195 @@
----
-title: Asa Api
-emoji: 🏆
-colorFrom: blue
-colorTo: blue
-sdk: docker
-pinned: false
-license: mit
-short_description: asa-api space
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# asa-api (Hugging Face Space)
+
+`asa-api` is a Docker-based API + GUI wrapper around [`asa::run_task()`](https://github.com/cjerzak/asa-software) designed for deployment as a Hugging Face Space.
+
+It uses:
+- `R` + `plumber` for HTTP endpoints
+- The `asa` package for orchestration (`run_task`, `run_task_batch`)
+- A lightweight password-protected browser GUI at `/`
+
+## What This Space Exposes
+
+1. `GET /healthz`
+2. `POST /v1/run` for a single prompt
+3. `POST /v1/batch` for many prompts
+4. `GET /` GUI page
+5. `POST /gui/query` used by the GUI
+
+## Security Model
+
+- API key auth is optional:
+  - If `ASA_API_KEY` is set, `/v1/*` requires:
+    - `Authorization: Bearer <key>` or
+    - `x-api-key: <key>`
+  - If `ASA_API_KEY` is not set, `/v1/*` is public.
+- GUI auth is password-based:
+  - `/gui/query` checks `GUI_PASSWORD` 
+
+## Required / Recommended HF Space Secrets
+
+Set these in the Hugging Face Space (`Settings` -> `Variables and secrets`):
+
+- `OPENAI_API_KEY` (or the provider key you use)
+- `GUI_PASSWORD`
+
+Optional secrets / vars:
+
+- `ASA_API_KEY` (enables API token auth for `/v1/*`)
+- `ASA_DEFAULT_BACKEND` (example: `openai`, `groq`, `anthropic`, `gemini`, `openrouter`)
+- `ASA_DEFAULT_MODEL` (example: `gpt-4.1-mini`)
+- `ASA_CONDA_ENV` (default: `asa_env`)
+- `ASA_USE_BROWSER_DEFAULT` (default: `false`, recommended for Space stability)
+- `CORS_ALLOW_ORIGIN` (default: `*`)
+
+Provider-specific keys supported by `asa` include:
+
+- `OPENAI_API_KEY`
+- `GROQ_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `GOOGLE_API_KEY` (or `GEMINI_API_KEY`)
+- `OPENROUTER_API_KEY`
+- Bedrock credentials if using `bedrock`
+
+## API Usage
+
+### 1) Health check
+
+```bash
+curl -s https://<your-space>.hf.space/healthz
+```
+
+### 2) Single query
+
+```bash
+curl -s https://<your-space>.hf.space/v1/run \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $ASA_API_KEY" \
+  -d '{
+    "prompt": "What is the population of Tokyo?",
+    "config": {
+      "backend": "openai",
+      "model": "gpt-4.1-mini"
+    },
+    "run": {
+      "output_format": "text",
+      "recursion_limit": 20
+    }
+  }'
+```
+
+### 3) Structured JSON output
+
+```bash
+curl -s https://<your-space>.hf.space/v1/run \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "Find Marie Curie birth year and nationality. Return JSON.",
+    "run": {
+      "output_format": "json"
+    }
+  }'
+```
+
+### 4) Batch query
+
+```bash
+curl -s https://<your-space>.hf.space/v1/batch \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompts": [
+      "What is the capital of France?",
+      "What is the capital of Japan?"
+    ],
+    "parallel": false,
+    "run": {
+      "output_format": "text"
+    }
+  }'
+```
+
+## Request Shape
+
+### `POST /v1/run`
+
+```json
+{
+  "prompt": "string, required",
+  "config": {
+    "...": "any asa::asa_config argument"
+  },
+  "run": {
+    "...": "any asa::run_task argument except prompt/config/agent"
+  },
+  "include_raw_output": false,
+  "include_trace_json": false
+}
+```
+
+### `POST /v1/batch`
+
+```json
+{
+  "prompts": ["required", "array", "of strings"],
+  "config": {
+    "...": "any asa::asa_config argument"
+  },
+  "run": {
+    "...": "run_task-compatible arguments shared across the batch"
+  },
+  "batch": {
+    "...": "any asa::run_task_batch argument except prompts/config/agent"
+  },
+  "parallel": false,
+  "include_raw_output": false,
+  "include_trace_json": false
+}
+```
+
+## Future Compatibility Strategy
+
+The adapter is intentionally resilient to `asa` changes:
+
+- It dynamically inspects `formals(asa::asa_config)`, `formals(asa::run_task)`, and `formals(asa::run_task_batch)`.
+- It only forwards request keys that exist in current function signatures.
+- This avoids hard crashes when upstream adds/removes optional args.
+
+## GUI
+
+- Open `/` in your browser.
+- Enter `GUI_PASSWORD`.
+- Enter prompt and choose output format.
+- Submit (Ctrl/Cmd + Enter is supported).
+
+## Docker Build and Runtime
+
+The `Dockerfile` clones `asa-software` during build and installs `asa` from source.
+
+Build args:
+
+- `ASA_SOFTWARE_REPO` (default: `https://github.com/cjerzak/asa-software`)
+- `ASA_SOFTWARE_REF` (default: `main`)
+
+Local build:
+
+```bash
+docker build -t asa-api .
+```
+
+Local run:
+
+```bash
+docker run --rm -p 7860:7860 \
+  -e OPENAI_API_KEY=... \
+  -e GUI_PASSWORD=XXX \
+  -e ASA_API_KEY=optional_token \
+  asa-api
+```
+
+Then open:
+- `http://localhost:7860/healthz`
+- `http://localhost:7860/`
+
+## Notes
+
+- Browser/Selenium tier is disabled by default (`use_browser = FALSE`) for better reliability in Space containers.
+- If you want browser tier, set `config.use_browser = true` explicitly per request and ensure supporting binaries are installed.