Fynx

Deterministic Content Intelligence Layer

Pattern-based content classifier designed for analytics, moderation, and marketplace teams. Classifies user reviews, descriptions, listings, and comments into categories with clean, deterministic outputs.

Why Fynx?

• Deterministic - Same input always produces same output
• Explainable - Every classification includes evidence with exact text spans
• Fast - 1000+ texts/second per instance
• Auditable - Full version tracking for compliance
• No ML required - Rule-based, no training data needed

Quick Start

1. Build

make build

2. Create a Policy Pack

Create packs/spam.yaml:

id: spam
name: Spam Detection
version: "1.0.0"

rules:
  - id: spam-001
    path: spam.promotional
    severity: high
    rationale: Contains promotional spam
    type: keyword_token
    keywords:
      - "buy now"
      - "limited offer"
      - "click here"

  - id: spam-002
    path: spam.contact
    severity: medium
    rationale: Contains contact solicitation
    type: regex
    pattern: '\b(call|text)\s*me\s*at\s*[\d\-]+'

3. Compile the Pack

# Generate signing keys (first time only)
./bin/fynx keygen --out fynx

# Compile pack
./bin/fynx pack build packs/spam.yaml -o packs/spam --key fynx.key

4. Run the Server

FYNX_PACKS_DIR=./packs ./bin/fynx-server

5. Classify Content

curl -X POST http://localhost:8080/classify \
  -H "Content-Type: application/json" \
  -d '{"text": "Buy now! Limited offer! Call me at 555-1234"}'

Response:

{
  "labels": [
    {"path": "spam.contact", "severity": "medium"},
    {"path": "spam.promotional", "severity": "high"}
  ],
  "evidence": [
    {
      "path": "spam.promotional",
      "rule_id": "spam-001",
      "rationale": "Contains promotional spam",
      "spans": [{"start": 0, "end": 7}, {"start": 9, "end": 22}],
      "pack_id": "spam",
      "pack_version": "1.0.0"
    },
    {
      "path": "spam.contact",
      "rule_id": "spam-002",
      "rationale": "Contains contact solicitation",
      "spans": [{"start": 24, "end": 45}],
      "pack_id": "spam",
      "pack_version": "1.0.0"
    }
  ],
  "meta": {
    "engine_version": "0.1.0",
    "pack_versions": ["spam@1.0.0"],
    "trace_id": ""
  }
}

API Reference

POST /classify

Classify text content.

Request:

{
  "text": "Content to classify",
  "request_id": "optional-trace-id",
  "include_matched_text": false
}

Response:

{
  "labels": [{"path": "category.subcategory", "severity": "high"}],
  "evidence": [{
    "path": "category.subcategory",
    "rule_id": "rule-001",
    "rationale": "Why this matched",
    "spans": [{"start": 0, "end": 10}],
    "pack_id": "pack-name",
    "pack_version": "1.0.0"
  }],
  "meta": {
    "engine_version": "0.1.0",
    "pack_versions": ["pack@1.0.0"],
    "trace_id": "request-id"
  }
}

GET /healthz

Liveness probe.

GET /readyz

Readiness probe (includes pack status).

GET /version

Engine and pack versions.

GET /metrics

Prometheus metrics.

Features

Web Dashboard

Fynx includes a built-in web dashboard for monitoring engine health, active packs, and testing rules in real-time.

# Enable dashboard via environment variable
FYNX_ENABLE_DASHBOARD=true ./bin/fynx-server

Access the dashboard at http://localhost:8080/dashboard.

Remote Registry & Hot-Swapping

Update policy packs without restarting the server. Fynx can fetch signed packs from a remote registry and swap them atomically.

# Configure registry and hot-swap interval
FYNX_REGISTRY_URL="https://registry.fynx.ai"
FYNX_HOTSWAP_INTERVAL="10m"

Rule Types

keyword_token

Matches whole words (tokens).

type: keyword_token
keywords:
  - spam
  - scam
case_sensitive: false

keyword_substring

Matches substrings anywhere in text.

type: keyword_substring
keywords:
  - "buy now"
  - "click here"

regex

Matches RE2 regular expressions.

type: regex
pattern: '\b\d{1,3}%\s*(off|discount)\b'
case_sensitive: false

Severity Levels

• info - Informational, no action needed
• low - Minor issue
• medium - Moderate concern
• high - Significant issue
• critical - Severe, immediate attention required

Configuration

Environment Variables

Variable	Description	Default
PORT	Server port	8080
FYNX_PACKS_DIR	Directory with compiled packs	./packs
FYNX_PUBLIC_KEY	Public key for signature verification	-
FYNX_AUTH_TOKENS	Comma-separated auth tokens	-

Docker

docker build -t fynx-server .
docker run -p 8080:8080 -v ./packs:/packs fynx-server

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: fynx
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: fynx
          image: fynx-server:latest
          ports:
            - containerPort: 8080
          env:
            - name: FYNX_PACKS_DIR
              value: /packs
          volumeMounts:
            - name: packs
              mountPath: /packs
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
          readinessProbe:
            httpGet:
              path: /readyz
              port: 8080

Example Packs

See examples/packs/ for ready-to-use policy packs:

• spam.yaml - Spam and promotional content detection
• abuse.yaml - Harassment, threats, and scam detection
• quality.yaml - Content quality assessment

Development

# Run tests
make test

# Run linter
make lint

# Build and run locally
make run

# Build Docker image
make docker

License

AGPL-3.0. Copyright (c) 2025 KikuAI Lab