File size: 4,532 Bytes
8616799
 
ad8bc9a
 
 
8616799
ad8bc9a
8616799
ad8bc9a
 
8616799
 
ad8bc9a
 
 
45b7965
 
 
 
 
ad8bc9a
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
45b7965
 
ad8bc9a
 
45b7965
 
 
 
 
ad8bc9a
45b7965
 
 
ad8bc9a
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
45b7965
 
 
 
 
 
 
ad8bc9a
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
45b7965
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
---
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`.