Spaces:
Running
Running
|
Download README.md from 2Btainment/Fuugi-API: direct link, hf CLI and curl.
- Browser
- Download file 4.53 kB
-
https://huggingface.co/spaces/2Btainment/Fuugi-API/resolve/main/README.md
- Command line
-
hf download hf://spaces/2Btainment/Fuugi-API/README.md
-
curl -L -o README.md https://huggingface.co/spaces/2Btainment/Fuugi-API/resolve/main/README.md
4.53 kB
| title: Fuugi API | |
| emoji: "\U0001F916" | |
| colorFrom: purple | |
| colorTo: yellow | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| license: mit | |
| short_description: Public Fuugi companion API for 2B Entertainment | |
| # Fuugi API | |
| FastAPI backend for the public Fuugi website companion. The service calls OpenRouter only from the | |
| server. It has no browser-visible API key and does not persist ordinary chat transcripts. | |
| An optional local SQLite learning memory stores only explicit `Merke dir:` notes after opt-in. The | |
| browser receives list/delete/revoke controls. Session tokens are HMAC-pseudonymized before storage, | |
| entries expire automatically, and saved notes are treated as untrusted data when sent to OpenRouter. | |
| ## API | |
| `GET /health` returns service readiness metadata without credentials. | |
| `GET /api/fuugi` returns endpoint metadata. `OPTIONS /api/fuugi` supports browser preflight. | |
| `POST /api/fuugi` accepts the widget contract: | |
| ```json | |
| { | |
| "companion": "fuugi", | |
| "message": "Was laeuft gerade bei 2B?", | |
| "messages": [ | |
| {"role": "user", "content": "Wer ist im Roster?"}, | |
| {"role": "assistant", "content": "ZmuReo, Evil Crow, KTN-Beats und 2B-Soundsystem."} | |
| ], | |
| "site": "https://2b-entertainment.com/", | |
| "locale": "de-DE" | |
| } | |
| ``` | |
| Response: | |
| ```json | |
| { | |
| "content": "Plain text or Markdown answer", | |
| "source": "openrouter", | |
| "model": "minimax/minimax-m3:free" | |
| } | |
| ``` | |
| ## Configuration | |
| Create the Hugging Face secret `OPENROUTER_API_KEY`. Do not create it as a public Space variable. | |
| No key is needed at image build time. | |
| Defaults: | |
| - Primary model: `minimax/minimax-m3:free` | |
| - Fallbacks: `minimax/minimax-m2.7:free`, `openrouter/free` | |
| - Production CORS: `2b-entertainment.com` with and without `www` | |
| - Rate limit: 15 requests per IP per 60 seconds | |
| - Total upstream timeout: 25 seconds across all model attempts | |
| - Internal reasoning enabled but excluded from API responses | |
| - Optional OpenRouter web-search server tool, bounded to one search and four results per request | |
| Web search is disabled by default because search engines can incur separate OpenRouter charges even | |
| when the selected language model is free. Enable it deliberately with `WEB_SEARCH_ENABLED=true`. | |
| See `.env.example` for all runtime controls. Localhost and explicit private-LAN IP origins are | |
| accepted only when `ENVIRONMENT=development`; public IP addresses and arbitrary hostnames remain | |
| blocked. | |
| Proxy headers are ignored by default. If a deployment needs `X-Forwarded-For`, set | |
| `TRUST_PROXY_HEADERS=true` and put only known immediate proxy CIDRs in | |
| `TRUSTED_PROXY_NETWORKS`. The Docker command disables Uvicorn's implicit proxy-header handling so | |
| the application can validate the original peer itself. | |
| ## Knowledge Maintenance | |
| `data/website_knowledge.json` is the only official website-fact snapshot sent to the model. Update | |
| it from public website files, preserve explicit `live`, `planned`, and `concept_surface` statuses, | |
| and never add credentials, private notes, deployment documents, or inferred promises. | |
| Inbound text, history, metadata, and knowledge values are marked as untrusted data beneath an | |
| immutable system policy. User-provided `system` roles are rejected. The model is instructed not to | |
| reveal prompts/secrets, obey embedded instructions, invent site facts, or claim privileged actions. | |
| ## Local Run | |
| ```bash | |
| python -m venv .venv | |
| . .venv/bin/activate | |
| pip install -r requirements-dev.txt | |
| export OPENROUTER_API_KEY="your-local-key" | |
| export ENVIRONMENT=development | |
| export CORS_LOCALHOST_ORIGINS="http://localhost:4173" | |
| uvicorn app.main:app --host 0.0.0.0 --port 7860 --no-proxy-headers | |
| ``` | |
| Do not put a real key in `.env.example`, source control, frontend JavaScript, request payloads, or | |
| Docker build arguments. | |
| ### Anonymous demand signals | |
| Set `MARKET_RESEARCH_ENABLED=true` to count broad allowlisted topic and intent categories per UTC | |
| day. The research store never receives raw questions, answers, IPs, sessions, free-form keywords, or | |
| visitor identifiers. `MEMORY_ENABLED` stays `false`; Fuugi does not recognize visitors across chats. | |
| The SQLite file requires persistent Space storage if counts must survive rebuilds or restarts. | |
| ## Verify | |
| Tests use a mocked upstream and a fake key; they make no OpenRouter or deployment calls. | |
| ```bash | |
| pip install -r requirements-dev.txt | |
| pytest -q | |
| ruff check . | |
| python -m compileall -q app tests | |
| ``` | |
| ## Docker | |
| ```bash | |
| docker build -t fuugi-api-space . | |
| docker run --rm -p 7860:7860 -e OPENROUTER_API_KEY="your-local-key" fuugi-api-space | |
| ``` | |
| Production Space: `2Btainment/Fuugi-API`. | |