Developer documentation
Build on the Wisent App platform.
Canonical contracts for iOS, Android, the web application, backend services, private media, data migrations, and signed messaging integrations.
Client surfaces
iOS
- Native Swift application with local-first chat and character workflows.
- App Store release metadata and TestFlight automation are release inputs, not runtime configuration.
- Room and persona state is owned by the authenticated account and synchronized through the application API.
Android
- Native Android client using the same authenticated application contracts.
- The package is com.wisent.android and is distributed through Google Play.
- Platform UI may differ; conversation, persona, document, and media ownership rules do not.
Service APIs
Application API
The web and mobile clients authenticate before calling the stateless application API. That service owns business logic and database access, while generation is delegated to a separately deployed authenticated inference service.
| Method | Path | Contract |
|---|---|---|
| POST | /api/chat | Run an authenticated conversation turn. |
| GET · POST | /api/conversations | List or create conversations. |
| GET | /api/conversations/search | Search the caller’s conversations. |
| GET · DELETE | /api/conversations/{id} | Read or remove one owned conversation. |
| GET · POST · DELETE | /api/personas | Manage caller-owned personas. |
| POST · GET | /api/documents | Upload or list caller-owned documents. |
| POST | /webhooks/user-inactivity | Receive the authenticated inactivity event. |
| GET | /health · /api/health | Report application-service health without coupling it to inference readiness. |
Inference and platform bridges
Inference, training, and App Store automation deploy independently from the application API. The inference service owns tokenization and generation; training consumes queued offline work; the App Store bridge verifies webhooks and emits normalized GitHub dispatches.
| Method | Path | Contract |
|---|---|---|
| POST | /v1/generate | Generate text as a blocking response or server-sent event stream. |
| GET | /health | Report inference readiness as ready, warming, or unhealthy. |
| POST | /webhooks/app-store-connect | Verify an App Store Connect webhook and dispatch its stable identifiers. |
| GET | /health | Report App Store webhook bridge process health. |
Off-platform messaging
Authenticated users can link an existing character and conversation to WhatsApp, Telegram, or iMessage. Linking returns a platform deep link; callers must treat delivery status separately from link creation.
| Method | Path | Contract |
|---|---|---|
| POST | /api/messaging/whatsapp/connect | Link a phone number and character to WhatsApp. |
| POST | /api/messaging/telegram/connect | Issue a single-use Telegram deep-link token. |
| POST | /api/messaging/imessage/connect | Link a phone number and character to iMessage. |
| GET | /api/messaging/status | Read the caller’s per-platform link state. |
Private image service
Generated image objects remain private under stado://wisent-images. The application returns only short-lived HMAC-signed proxy URLs; clients never receive object-store credentials.
| Method | Path | Contract |
|---|---|---|
| POST | /image-generate/ | Create an image-generation job. |
| GET | /image-generate/images/{uuid}.{ext} | Read an authorized image through the signed proxy. |
| GET | /image-generate/health | Report image pipeline readiness. |
| GET | /health | Report process health. |
Local MLX backend
Apple Silicon deployments provide local model inference, JWT authentication, control-vector training, and multi-armed-bandit notification scheduling without silently falling back to a remote provider.
| Method | Path | Contract |
|---|---|---|
| POST | /api/chat | Run local model inference. |
| GET · POST | /api/control_vectors | List or train control vectors. |
| GET | /api/job/{id} | Read the durable state of a training job. |
| GET · POST | /api/mab/notifications/{schedule|statistics|pending|history} | Operate and inspect the notification bandit. |
Data and migrations
Canonical schema
- wisent-supabase-wisent-app migrations are the schema source for project rbqjqnouluslojmmnuqi.
- Pull-request CI checks migrations; the default branch is the deployment boundary.
- Application code must not treat dashboard edits or local snapshots as canonical schema.
Optimization service
- Supported steering comparisons include CAA, DAC, BiPO, REFT, and RepEng.
- Requests identify steering type and layer configuration explicitly.
- Optimization results are versioned artifacts; clients do not infer compatibility from filenames.
Tour messaging bridge
The FastAPI bridge exposes GET /health and signed POST /webhook. A webhook is admitted only for x-webhook-event: message.received, a timestamp no more than five minutes old, and an HMAC-SHA256 signature over <timestamp>.<raw body>.
- Resolve the sender through Supabase
imessage_users; unlinked senders receive account-link guidance. - Detect explicit travel or location intent.
- Call
POST /api/messaging/tour-chatwith{ messages, user_id, location? }andx-agent-secret. - Reply through Ultrareach
POST /v3/chats/{chat_id}/messageswith the service bearer.
Required secrets: SERVICE_API_TOKEN, AGENT_TOOL_SECRET, SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, and TOUR_BRIDGE_SIGNING_SECRET(S). Optional bases default to local Ultrareach on port 8080 and https://app.wisent.ai.