Concepts

The core idea

fluidsoul is a behavior layer, not a component library. It sits between your app and your UI decisions, answering: "Who is this user, and what should we show them?"

You send events → fluidsoul runs rules → you get back a context profile → you adapt your UI.

Workspaces

A workspace is an account boundary. Each workspace has:

• A unique ID (UUID)
• An API token for authentication
• A rules config that defines how events are classified
• Independent event and context data

Events

Events are user actions you record. Each event has:

• user_id — who did it
• event_type — what they did (e.g. "report_viewed", "feature_accessed")
• metadata — optional key-value details (e.g. { "platform": "mobile" })
• event_time — when it happened

Events are the raw input to the rules engine.

Context

A computed context is the output of the rules engine — a profile describing a user:

Rules config

Each workspace has a rules config (JSON) that controls classification. It includes:

• Dimensions — classification axes (e.g. "user_role" with values "analyst", "executive")
• Signals — which events/metadata map to which dimension values
• Thresholds — ratio for dominant classification (default: 0.7)
• Feature defaults — per-category feature priority lists
• Recommended defaults — per-category default settings
• Engagement thresholds — configurable event count thresholds
• Maturity thresholds — configurable breadth and time thresholds

See Configuring Rules for the full schema.

The rules engine

The rules engine is deterministic — same events + same config = same context. No randomness, no LLM involved in classification.

1. For each event, check all signal conditions
2. Count matches per dimension value
3. If the dominant value exceeds the threshold → classify as that value
4. Otherwise → classify as the hybrid value
5. Compute engagement from recent activity
6. Compute maturity from feature breadth and time since first event
7. Generate explainability text

LLM narrative (optional)

On top of rules, you can enable an optional LLM-generated user narrative — a 2–4 sentence natural-language summary of who this user is. This is additive; the rules engine always runs first.

Set FLUIDSOUL_LLM_PROVIDER, FLUIDSOUL_LLM_API_KEY, and FLUIDSOUL_LLM_MODEL environment variables on your API server.

Context refresh

Context is not automatically recomputed on every event. You explicitly trigger a refresh:

POST /v1/context/refresh
{ "user_id": "user_123" }

This is intentional — it lets you batch events and refresh at natural session boundaries.

Explainability

Every context includes plain-English explanations:

[
  "Classified as 'analyst' based on 12 analyst and 3 executive signals out of 47 total events.",
  "Engagement level is 'high' based on recent activity in the last 30 days."
]

Confidence scores

Each inference comes with a confidence score (0–1):

{
  "user_category": 0.85,
  "preferred_mode": 0.72,
  "engagement_level": 0.9,
  "user_maturity": 0.7
}

Fallback behavior

If no context exists yet (new user, no events), getContext() returns null. Always handle this case by showing your default layout.

Privacy

fluidsoul provides GDPR-ready endpoints:

• POST /v1/privacy/export — export all data for a user
• DELETE /v1/privacy/delete — delete all data for a user

Audit logs

Every API action is recorded in an append-only audit log, queryable via GET /v1/audit/logs.