begeniux 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BeGeniux contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,311 @@
+# begeniux
+
+**Behaviorally-adaptive UI through LLM agents and the AG-UI protocol.**
+
+Most generative UI today reacts to *prompts*. **BeGeniux reacts to behavioral traces** — clicks, scrolls, hovers, dwells — and re-renders the UI to match observed user behavior, in real time, at session granularity.
+
+You wrap a region of UI in `<BeGenSurface>`, pass in a set of variant components and a `classify` function. The library handles behavior tracking, summarization, and variant swapping. Bring your own LLM — Gemini, Claude, OpenAI, a heuristic, anything that satisfies `ClassifyFn`.
+
+---
+
+## Why this exists
+
+Adaptive UI research is 30+ years old. SUPPLE (2004) showed UIs could regenerate per-user. Contextual bandits (2010) showed online learning could pick layouts. Implicit-feedback work (2005) showed clicks already encode preference. None of this shipped at scale. Why?
+
+- **Hand-coded rules** couldn't keep up with the combinatorics of real UIs.
+- **Shallow ML** needed huge population-level traffic to converge — too slow for a single session.
+- **A/B tests** optimize *populations*, not *individuals* — the wrong granularity.
+
+In-context learning (GPT-3 onward) finally cracked it. An LLM can reason from a handful of behavioral signals to a sensible UI choice, **without training, without traffic, in one session**. That's the unlock.
+
+```mermaid
+flowchart LR
+  subgraph Trad["Today's generative UI"]
+    direction LR
+    P["💬 User<br/>prompt"] --> M1["LLM"] --> U1["Generated UI"]
+  end
+  subgraph Be["BeGeniux"]
+    direction LR
+    B["🖱️ Behavioral trace<br/>clicks · scrolls · hovers · dwells"] --> M2["LLM<br/>as policy"] --> U2["Adapted UI<br/>session-granular"]
+  end
+  Trad ~~~ Be
+```
+
+> Our contribution is the combination of three ideas that have not been combined before: **interaction traces as the input modality** (not text prompts), **LLM agents as the policy** (not hand-coded rules or shallow classifiers), and **session-granularity adaptation** (not population-level A/B tests) — under developer-declared invariants that keep the policy honest. The first two are 2024+ technology that finally make 30 years of adaptive UI research tractable.
+
+### The goal
+
+Make any web region **behaviorally adaptive** with one component swap. The developer keeps full control of the variants — the library only decides *which* one is rendered, *when*, and *why* (with the LLM's reasoning string attached).
+
+---
+
+## How it works
+
+Every `<BeGenSurface>` runs a tight loop, scoped to its own DOM region:
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant U as User
+  participant T as useBehaviorTracker
+  participant S as BeGenSurface
+  participant C as classify (your code)
+  participant V as Active variant
+
+  U->>T: clicks · scrolls · hovers · dwells
+  Note over T: Ring buffer of last 50 events<br/>(scoped to this surface only)
+  T->>T: Every 10 events OR 5s →<br/>compute BehaviorSummary
+  T->>S: BehaviorSummary
+  S->>S: rate-limit gate (≥4s since last call)
+  S->>C: classify(summary)
+  Note over C: Your LLM / AG-UI route /<br/>heuristic — anything matching ClassifyFn
+  C-->>S: AgentDirective<br/>{variant, confidence, reasoning}
+  S->>V: mount variants[directive.variant]<br/>with variantProps
+  V->>U: new UI · ≤ 2s round-trip
+```
+
+Three things keep this honest:
+
+1. **Listeners scoped to the container element**, not `window` — two surfaces side-by-side never cross-pollute events.
+2. **Rate limit on `classify`** (default 4s) — caps cost and prevents thrash.
+3. **Errors keep the current variant.** A classifier failure never crashes the UI; the user just stays on what they had.
+
+---
+
+## Where it fits in your stack
+
+The library is one layer. You bring your variants and your policy:
+
+```mermaid
+flowchart TB
+  subgraph YourApp["Your application"]
+    direction TB
+    Page["Page / Route"]
+    Variants["Your variant components<br/>DenseGrid · DeliberateGrid · NeutralGrid"]
+    Classify["Your classify function"]
+    Page --> Surface
+    Surface -->|renders one of| Variants
+    Surface -->|invokes| Classify
+  end
+
+  subgraph Lib["begeniux (this package)"]
+    direction TB
+    Surface["&lt;BeGenSurface&gt;"]
+    Provider["&lt;BeGenProvider&gt;"]
+    Tracker["useBehaviorTracker"]
+    Ctx["BeGenContext"]
+    Surface -.uses.-> Tracker
+    Surface -.publishes to.-> Ctx
+    Provider -.exposes.-> Ctx
+  end
+
+  subgraph Policy["Behind your classify fn (you choose)"]
+    direction TB
+    Gemini["Gemini 2.0 Flash<br/>via createGeminiClassifier"]
+    AGUI["AG-UI / CopilotKit route"]
+    Anth["Claude / OpenAI / local model"]
+    Heur["createHeuristicClassifier<br/>(zero-dep fallback)"]
+  end
+
+  Classify -.-> Gemini
+  Classify -.-> AGUI
+  Classify -.-> Anth
+  Classify -.-> Heur
+```
+
+**Nothing in this library imports CopilotKit, AG-UI SDK, Next.js, or any LLM SDK.** It runs anywhere React 18+ runs. The agent backend is a `ClassifyFn` injection — that's the entire integration surface.
+
+---
+
+## The contract
+
+Three types are the entire boundary between your code and the library:
+
+```mermaid
+flowchart LR
+  E["BehaviorEvent[]<br/><i>click · scroll · hover · dwell</i>"]
+  S["BehaviorSummary<br/><i>clicks_per_min, avg_dwell_ms,<br/>scroll_depth, hover_count,<br/>events_seen, page_context</i>"]
+  D["AgentDirective<br/><i>variant · confidence · reasoning</i>"]
+  V["Rendered variant"]
+
+  E -->|tracker aggregates| S
+  S -->|ClassifyFn = your policy| D
+  D -->|surface selects| V
+```
+
+In code:
+
+```ts
+type ClassifyFn = (summary: BehaviorSummary) => Promise<AgentDirective>;
+
+type BehaviorSummary = {
+  clicks_per_min: number;
+  avg_dwell_ms: number;
+  scroll_depth: number;        // 0–1
+  hover_count: number;
+  events_seen: number;         // saturates at 50
+  page_context: { route: string; visible_product_ids: string[] };
+};
+
+type AgentDirective = {
+  variant: "decisive" | "deliberate" | "neutral";
+  confidence: number;          // 0–1
+  reasoning: string;           // one-sentence English
+};
+```
+
+Whatever you put behind `ClassifyFn` — Gemini, Claude, OpenAI, a CopilotKit/AG-UI route, a hand-tuned regex — it's the policy that decides which variant the user sees. Freeze these types and the library and your agent backend evolve independently. See [`src/types.ts`](./src/types.ts) for the canonical definitions.
+
+---
+
+## Install
+
+```bash
+npm install begeniux
+```
+
+Peer dependencies: `react@>=18`, `react-dom@>=18`. The library has zero runtime dependencies and works without CopilotKit, AG-UI, or any specific LLM SDK.
+
+## Quick start
+
+```tsx
+import {
+  BeGenProvider,
+  BeGenSurface,
+  createGeminiClassifier,
+} from "begeniux";
+
+const classify = createGeminiClassifier({
+  apiKey: process.env.NEXT_PUBLIC_GEMINI_KEY!,
+});
+
+export default function App({ products }) {
+  return (
+    <BeGenProvider>
+      <BeGenSurface
+        variants={{
+          decisive: DenseGrid,
+          deliberate: DeliberateGrid,
+          neutral: NeutralGrid,
+        }}
+        variantProps={{ products }}
+        classify={classify}
+        pageContext={{
+          route: "/products",
+          visible_product_ids: products.map((p) => p.id),
+        }}
+      />
+    </BeGenProvider>
+  );
+}
+```
+
+That's the whole integration. The surface tracks behavior in its DOM region, calls `classify` on a debounce, and swaps the rendered variant component when the directive changes.
+
+## API
+
+| Export | What it does |
+|---|---|
+| `<BeGenProvider>` | Context provider for surface state. Required if you want to call `useBeGenContext()` from a child. |
+| `<BeGenSurface>` | The main component. Tracks behavior, calls `classify`, renders the active variant. |
+| `useBehaviorTracker(opts)` | Low-level hook for custom integrations — same engine the surface uses. |
+| `useBeGenContext()` | Reads the current `variant`, `directive`, and `summary` from context. |
+| `createGeminiClassifier(opts)` | Returns a `ClassifyFn` that calls Google's Gemini API directly. |
+| `createHeuristicClassifier()` | Zero-dependency heuristic fallback. Useful for offline dev and demos. |
+| `PERSONAS` | Pre-canned behavior traces (`decisive`, `deliberate`) for deterministic demos via `seedPersona`. |
+
+Full type signatures live in [`src/types.ts`](./src/types.ts) — that file is the contract between the library and the consumer (also visualized [above](#the-contract)).
+
+## Wiring AG-UI / CopilotKit
+
+The library is intentionally agnostic to the agent backend. To route through CopilotKit/AG-UI, write a thin `ClassifyFn`:
+
+```tsx
+const classify: ClassifyFn = async (summary) => {
+  const res = await fetch("/api/copilotkit", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ tool: "classify_behavior", summary }),
+  });
+  return res.json();
+};
+```
+
+Your route is responsible for invoking the agent and returning a JSON body that matches `AgentDirective`. The library never imports CopilotKit directly — keeping the package install-anywhere.
+
+## Determinism for demos
+
+Pass `seedPersona="decisive"` or `seedPersona="deliberate"` to `<BeGenSurface>` and the surface will pre-seed its tracker with a canned trace. Within a couple of seconds of mount you'll get a stable directive — useful for split-screen demos, screenshots, and judges.
+
+```tsx
+<BeGenSurface
+  variants={variants}
+  classify={classify}
+  pageContext={pageContext}
+  seedPersona="decisive"
+/>
+```
+
+The traces live in [`src/personas.ts`](./src/personas.ts) — feel free to tune them.
+
+## Reading state from children
+
+Wrap with `<BeGenProvider>` (or place provider above the surface) and call `useBeGenContext()`:
+
+```tsx
+function TelemetryStrip() {
+  const { variant, directive, summary } = useBeGenContext();
+  return (
+    <div>
+      Mode: {variant}
+      {directive && ` · ${directive.reasoning}`}
+      {summary && ` · ${summary.events_seen} events`}
+    </div>
+  );
+}
+```
+
+Nice for debugging, demo overlays, or analytics.
+
+## Local development
+
+```bash
+git clone <this repo>
+cd packages/begeniux
+npm install
+npm run build           # one-shot build to dist/
+npm run dev             # tsup --watch
+
+cd examples/basic
+npm install
+npm run dev             # http://localhost:5180
+```
+
+The example imports from `../../src/index.ts` via a Vite alias, so source changes hot-reload. Two seeded surfaces render side-by-side using the heuristic classifier — no API keys required.
+
+## Research lineages
+
+This library combines four threads of prior work that have rarely been combined in production UI:
+
+- **Adaptive User Interfaces** — Gajos & Weld, *SUPPLE: Automatically Generating User Interfaces* (IUI 2004).
+- **Contextual bandits** — Li et al., *A Contextual-Bandit Approach to Personalized News Article Recommendation* (WWW 2010).
+- **Implicit feedback / behavior modeling** — Joachims et al., *Accurately Interpreting Clickthrough Data as Implicit Feedback* (SIGIR 2005).
+- **In-context learning as policy** — Brown et al., *Language Models are Few-Shot Learners* (NeurIPS 2020).
+
+The novel contribution is the combination: behavioral traces as input, LLM agents as policy, session-granularity adaptation, with developer-declared invariants.
+
+## Roadmap
+
+- Multi-armed bandit policies (Thompson sampling) for variant selection.
+- **Invariant DSL** — declare UI properties that must hold across variants (e.g., "cancel button always reachable", "checkout step never re-ordered").
+- Behavior embeddings for open-ended UI generation beyond a fixed variant set.
+- Eval harness with replay traces and counterfactual scoring.
+- First-class adapters for CopilotKit, LangGraph, Mastra, and the Anthropic SDK.
+
+## Contributing
+
+PRs welcome. Keep the public surface small — anything not exported from `src/index.ts` is private. Don't bundle React; don't add heavy dependencies; don't assume Next.js. The library should drop into Vite, CRA, Remix, Next, or anywhere React 18+ runs.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).