BridgeBrain Developer Integration Guide

Version 1.0 — Build with Licensed AI Personas

BridgeBrain allows developers to integrate authenticated, licensed digital personas into any application — web apps, mobile music tools, games, voice assistants, VR, creative tools, and more.

BridgeBrain provides:

PTP (Persona Transfer Protocol) → How a persona is structured.
PLF (Persona Licensing Framework) → How rights & royalties are enforced.
SDK + REST API → How your app talks to personas.

BridgeBrain is the Identity + Digital Rights Layer, not the AI model itself.
You can use:
✅ BridgeBrain’s hosted inference
✅ OpenAI
✅ Claude
✅ Gemini
✅ Local / on-device models (LLAMA, Mistral, etc.)

Your choice.

1. Install the Plugin (WordPress Core Requirement)

Upload bridgebrain-sdk-api-fixed.zip to WordPress
Activate it
Go to BridgeBrain → Settings
Copy your API Key (shown as the JWT Secret / API Token)
Use that key in your app as the request header:

X-BridgeBrain-Key: YOUR_API_KEY_HERE

That’s your app’s authentication layer.

2. Key Concepts

Term	Meaning
Persona	A structured identity (tone, narrative style, behavior constraints, knowledge).
PTP Container	The signed persona definition file your app loads.
License	Defines who can use the persona & in what context.
License Proof (JWT)	Cryptographic token your app uses to verify rights.
Usage Reporting	You report key usage metrics → royalties are auto-calculated.
Hosted or BYO LLM	You choose where AI inference happens.

3. API Endpoints

Base URL:

https://yourdomain.com/wp-json/bb/v1

Method	Endpoint	Description

POST /personas Create a persona (server/admin).

GET /personas/{id} Retrieve persona PTP container.

POST /licenses Issue a license to a user/app.

POST /licenses/{id}/verify Validate a license proof.

POST /usage Report usage events (tokens, minutes, requests).

GET /usage/reports View metered usage totals.

GET /marketplace/search Search personas available for licensing.

4. Integration Model Options

You can use BridgeBrain in two ways:

Option A — BridgeBrain Hosted Processing (Easiest)

Your app sends messages → persona responds → everything tracked automatically.

Option B — Bring Your Own Model (BYO LLM)

Your app loads persona identity → generates prompts → runs inference using your own models → reports usage.

This is ideal for:

Music apps
Voice apps
On-device apps
Enterprise data privacy workflows

5. Quick Start — Web App Example (Hosted Processing)

import { BridgeBrain } from "@bridgebrain/sdk-web";

const bb = new BridgeBrain({ apiKey: process.env.BB_KEY });

// Load persona
const persona = await bb.personas.load("writing-coach-001");

// Start conversation session
const session = await persona.session.start({ userId: "user-445" });

// Send text and receive persona response
const reply = await session.send("Help me write a positive, confident bio.");
console.log(reply.text);

No licensing logic required — SDK handles it.

6. Music App Example (BYO Local / Custom Model)

import { BridgeBrain } from "@bridgebrain/sdk-core";
import { runLocalModel } from "./local-llama-runner.js";

const bb = new BridgeBrain({ apiKey: process.env.BB_KEY });

// Load licensed musician persona
const persona = await bb.personas.load("legendary-producer-001");

// Create runtime session
const session = await bb.sessions.create({ persona });

// Use persona to generate structured prompts:
const prompt = session.generatePrompt("Generate a neo-soul chord progression in A minor.");

// Run the inference on your own LLM / device / GPU
const output = await runLocalModel(prompt);

// Report usage for royalty attribution
await session.reportUsage({ tokens: output.tokenCount });

return output.text;

This keeps persona rights & royalties enforced
even when you are not using our servers.

7. Podcast / Voice Streaming Example

const session = await bb.sessions.live.start({
  persona: "mark-twain-official",
  voice: "warm-narrator"
});

mic.on("data", async (inputAudio) => {
  await session.sendAudio(inputAudio);
});

session.on("audio_out", (spokenResponse) => {
  playToPodcastOutput(spokenResponse);
});

8. License Control Flow (Short Summary)

App issues a license to a user:

POST /licenses

Your app receives a license proof (JWT)

Before persona use, app verifies proof:

POST /licenses/{id}/verify

2. Your app receives a license proof (JWT)

3. Before persona use, app verifies proof:

POST /licenses/{id}/verify

App reports usage:

POST /usage

Payouts happen automatically based on consumption.

9. Usage Reporting Example

curl -X POST https://yourdomain.com/wp-json/bb/v1/usage \
  -H "X-BridgeBrain-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "app_id": "com.yourapp",
        "persona_id": "legendary-producer-001",
        "type": "tokens",
        "value": 1850
      }'

10. Royalty Settlement

BridgeBrain tracks:

Persona usage across apps
License tiers and entitlements
Creator & platform royalty splits

Creators get payouts.
You don’t have to calculate anything manually.

11. Marketplace Access

Search for personas that can be licensed:

GET /marketplace/search?q=music

Returns:

[
  { "persona_id": "legendary-producer-001", "display_name": "The Producer" },
  { "persona_id": "jazz-piano-maestro", "display_name": "Maestro of Keys" }
]

12. Best Practices

Tip	Why
Always report usage	Ensures correct royalties & legal compliance
Keep license proofs short-lived	Enhances security
Use persona tone & rule prompts exactly	Maintains persona integrity
Do not alter PTP container content	Persona authenticity matters

13. Support & Extending

If you want:

Model adapters
Custom persona onboarding flows
Registrar / sector licensing
Bulk enterprise activation

We support those workflows.

You’re Ready.

Your app now has the ability to host real, legal, revenue-generating digital personas.

This is how AI becomes personal, human, fair, and creator-sustaining.

BridgeBrain SDK and API