Obelaw SystemOne

SystemOne is the modular Core Decision Engine for the Obelaw ecosystem. It re-architects how modern Laravel applications integrate artificial intelligence by replacing slow, open-ended conversational generation with typed decision primitives evaluated deterministically against arbitrary application states.

Instead of prompting an LLM to “write a response” and hoping for valid JSON, SystemOne formulates crisp probabilistic questions—such as Bernoulli likelihoods, categorical classifications, or rubric scores—and returns calibrated probabilities in milliseconds.

flowchart TD
    AppState["Application State<br/><i>'User ID 4082 requested $12,500 transfer from unrecognized IP'</i>"]

    subgraph Engine["SystemOne Decision Engine"]
        direction LR
        Q1["Noul (Binary)<br/><b>Is this fraud?</b>"]
        Q2["Choice (Categorical)<br/><b>Mitigation route</b>"]
        Q3["Score (Rubric)<br/><b>Risk score 1-10</b>"]
    end

    Driver["Cloudflare Workers AI (Clef Driver)<br/><code>@cf/cloudflare/clef</code> (Edge-Fast, &lt;100ms)"]

    Response["DecisionResponse<br/><code>is_fraud: 0.98</code> (positive) | <code>action: 'challenge'</code> | <code>risk: 9.4/10</code>"]

    AppState --> Engine
    Engine --> Driver
    Driver --> Response

The Paradigm Shift

Why Unstructured LLMs Fail in Business Logic

Standard Large Language Models (LLMs) are designed for conversational generation. Using them for programmatic business decisions introduces severe reliability and engineering problems:

1. Hallucination Risk: Text completion models invent facts, non-existent identifiers, or arbitrary outcomes.
2. Schema Inconsistency: Even with JSON-mode prompting, LLMs frequently emit malformed keys, invalid datatypes, or unexpected commentary outside the JSON block.
3. Excessive Latency: Autoregressively generating 200 tokens across conversational transformers takes 1,500ms to 4,000ms—unacceptable for synchronous HTTP requests or checkout pipelines.
4. Token Bloat & Cost: Passing elaborate system prompts and formatting instructions inflates token bills by 10x to 50x.

flowchart LR
    subgraph Traditional["Unstructured LLMs (Generative / System 2)"]
        direction TB
        T1["Prompt + Context String"] --> T2["Slow Autoregressive Generation<br/>(1,500ms - 4,000ms)"]
        T2 --> T3["Unpredictable String / Loose JSON<br/>(Hallucination &amp; Schema Drift)"]
    end

    subgraph SystemOneFlow["SystemOne Decision Engine (System 1)"]
        direction TB
        S1["Typed State Payload"] --> S2["Parallel Edge Inference<br/>(&lt;100ms via Workers AI)"]
        S2 --> S3["Strictly Typed DecisionResponse<br/>(Probabilities, Enums, Bounded Scores)"]
    end

The System 1 Cognitive Model

Named after psychologist Daniel Kahneman’s dual-process cognitive theory in Thinking, Fast and Slow:

• System 1 (Fast & Intuitive): Automatic, fast, perceptual, and calibrated probability calculations.
• System 2 (Slow & Deliberative): Slow, analytical, multistep reasoning, and sequential generation.

Obelaw SystemOne brings System 1 intuition to Laravel. It bypasses open-ended generative reasoning and executes fast, calibrated decision queries directly at the network edge.

Ecosystem Packages

The SystemOne architecture is split into decoupled, modular packages:

flowchart TD
    App["Laravel Application"]

    subgraph CorePkg["obelaw/systemone (Core Engine)"]
        Facade["SystemOne Facade"]
        Builder["DecisionRequest Builder"]
        Primitives["Primitives: Noul, Choice, Score"]
        Contracts["Driver & Response Contracts"]
    end

    subgraph DriverPkg["obelaw/systemone-clef (Edge Driver)"]
        ClefAdapter["ClefDriver Adapter"]
        Config["config/clef.php"]
    end

    Cloudflare["Cloudflare Workers AI<br/><code>@cf/cloudflare/clef</code>"]

    App --> Facade
    Facade --> Builder
    Builder --> Primitives
    Builder --> Contracts
    Contracts -.-> ClefAdapter
    ClefAdapter --> Config
    ClefAdapter -->|"HTTPS &lt;100ms"| Cloudflare

Requirements

• PHP: 8.2 or higher
• Laravel: 10.0, 11.0, 12.0, or 13.0
• Cloudflare Account (optional for local mocking, required for live Workers AI)

Installation

Install both the core engine and the Cloudflare Clef driver via Composer:

composer require obelaw/systemone obelaw/systemone-clef

Publish Driver Configuration

Publish the clef.php configuration file:

php artisan vendor:publish --tag="systemone-clef-config"

Configure your Cloudflare Workers AI credentials in .env:

CLOUDFLARE_ACCOUNT_ID=your-cloudflare-account-id
CLOUDFLARE_API_TOKEN=your-cloudflare-workers-ai-api-token
CLOUDFLARE_AI_MODEL=@cf/cloudflare/clef

60-Second Quickstart

Here is how simple it is to evaluate complex security state in a single request:

use Obelaw\SystemOne\Facades\SystemOne;
use Obelaw\SystemOne\Primitives\Noul;
use Obelaw\SystemOne\Primitives\Choice;
use Obelaw\SystemOne\Primitives\Score;

// 1. Define application state context
$context = "User 'sarah_admin' logged in from Lagos, Nigeria. Previous session was 12 minutes ago from London, UK. Two factor SMS failed twice.";

// 2. Ask multiple typed questions in one atomic call
$response = SystemOne::state($context)
    ->ask('is_compromised', Noul::make('Is this account likely compromised?'))
    ->ask('mitigation', Choice::make('Recommended security action', [
        'allow' => 'Ignore and allow normal session',
        'step_up' => 'Require biometric passkey challenge',
        'lock_account' => 'Lock account and terminate all active sessions',
    ]))
    ->ask('urgency', Score::rubric('Rate incident escalation priority', [
        'Low', 'Medium', 'High', 'Critical'
    ]))
    ->run();

// 3. Consume strictly typed results
if ($response->isPositive('is_compromised', threshold: 0.8)) {
    $action = $response->value('mitigation'); // "lock_account"
    $confidence = $response->confidence('mitigation'); // 0.94
    $urgencyScore = $response->value('urgency'); // 4.0 ("Critical")

    Log::alert("Security trigger executed: {$action} (Confidence: {$confidence})");
}

Key Benefits

• Deterministic Primitives: Work with float probabilities, categorized string keys, and numeric score ranges—not unpredictable string dumps.
• Atomic Multi-Question Requests: Ask 5 questions simultaneously against the same state payload in one single network request.
• Edge Inference: Cloudflare Workers AI processes requests close to users across 300+ edge locations in under 100 milliseconds.
• 100% Mockable & Testable: Ships with complete testability. Use Laravel’s Http::fake() or mock drivers to test business logic with zero token costs.
• Zero Hallucination Surface: Models are bound by the criteria you define in the primitive schema.

Documentation Roadmap

1. Decision Primitives: Deep dive into Noul, Choice, and Score.
2. Fluent API & Builder: Complete guide to DecisionRequest and DecisionResponse.
3. Cloudflare Clef Driver: Configuration, endpoint routing, and timeouts.
4. Custom Drivers: Implementing custom AI providers and local LLM runners.
5. Testing & Mocking: Testing decision pipelines using Pest and PHPUnit.