# Bibividi

**Token/Quota optimization middleware for AIs**
Intercepts Anthropic / OpenAI / Gemini / Groq / Mistral / Ollama requests, runs a matching Python script locally, and sends a condensed prompt — reducing token consumption by **60–95%**.
Turn each solved prompt into a reusable program. Your library grows. Your AI bill shrinks — or your free-tier daily quota goes further.

```
Your app/Your prompt ──► BIBIVIDI proxy :8080 ──► Anthropic / OpenAI / Gemini
                   │
         Matching engine (embeddings)
                   │
     Script found → local Python execution
                   │
         Condensed context (90% fewer tokens)
```

No prompt is ever stored. Processing is 100% local.

---

## Quick start

**Desktop app (recommended)** — download the installer for your platform from [Releases](https://github.com/bibividi/bibividi/releases). The proxy starts automatically on launch.

**CLI**
```bash
pip install bibividi
bibividi start                    # proxy starts on :8080
bibividi add scripts/pdf-clause-extractor/
bibividi status
```

### Integrate in 2 lines

**Anthropic SDK**
```python
import anthropic
from bvd.sdk import anthropic_http_client

client = anthropic.Anthropic(
    api_key="sk-ant-...",
    http_client=anthropic_http_client(),   # ← only change
)
# All calls now route through BIBIVIDI — zero code changes elsewhere
```

**OpenAI SDK**
```python
import openai
from bvd.sdk import openai_http_client

client = openai.OpenAI(
    api_key="sk-...",
    http_client=openai_http_client(),      # ← only change
)
```

**Async variants**
```python
from bvd.sdk import async_anthropic_http_client, async_openai_http_client

client = anthropic.AsyncAnthropic(http_client=async_anthropic_http_client(), ...)
```

---

## What is a BSS skill?

A **BSS (BIBIVIDI Skill Specification) pack** is a directory with two files:

| File | Role |
|------|------|
| `skill.json` | Metadata: `id`, `name`, `description`, `tags`, `hash` |
| `skill.py` | Python script. Reads `PROMPT`, prints condensed output to stdout |

```python
# skill.py — PROMPT is injected automatically
import re, json

clauses = re.findall(r'(?:Article|Clause)\s+\d+[^.]*\.', PROMPT)
print(json.dumps({"clauses": clauses[:10], "total": len(clauses)}))
```

```bash
bibividi add  scripts/my-skill/    # install
bibividi list                       # inspect
bibividi test my-skill-id           # run against stdin
```

**Sandbox**: only `json, re, math, statistics, datetime, collections, itertools,
functools, pathlib, string, textwrap, csv, io, base64, hashlib, uuid` are allowed.
No OS, network, or subprocess access. Scripts are SHA-256 verified on install.
Ed25519 signatures supported for marketplace packs.

### Included skill library (26 packs)

**Demo packs**

| Pack | Typical saving |
|------|---------------|
| `pdf-clause-extractor` | 80–95% |
| `csv-data-summarizer` | 85–95% |
| `structured-report-extractor` | 75–90% |
| `batch-translation-condenser` | 70–90% |
| `code-review-condenser` | 60–80% |

**Office productivity**

| Pack | What it extracts | Typical saving |
|------|-----------------|---------------|
| `email-thread-condenser` | Action items, decisions, timeline from email threads | 75–90% |
| `meeting-notes-structurer` | Agenda, decisions, action items from meeting notes | 70–85% |
| `slack-thread-distiller` | Key decisions and outcomes from Slack threads | 70–88% |
| `cv-profile-extractor` | Skills, experience, education from CVs/résumés | 75–90% |
| `job-posting-parser` | Role, requirements, salary from job descriptions | 70–85% |
| `expense-report-analyzer` | Totals, categories, anomalies from expense reports | 80–90% |
| `invoice-parser` | Line items, totals, parties from invoices | 80–92% |
| `sales-pipeline-condenser` | Stage breakdown, top deals, at-risk from CRM exports | 75–90% |
| `customer-feedback-synthesizer` | Sentiment, themes, praise/complaints from reviews | 80–92% |
| `requirements-to-stories` | User stories grouped by epic from PRDs/specs | 60–80% |
| `project-status-condenser` | RAG status, completed/blocked/next-steps from status reports | 70–85% |
| `legal-contract-summarizer` | Parties, term, obligations, key clauses from contracts | 85–95% |
| `support-ticket-analyzer` | Priority distribution, categories, critical tickets from ticket batches | 75–90% |

**BSS 1.1 chain pipelines**

| Pack | Pipeline | Typical saving |
|------|----------|---------------|
| `document-intelligence-suite` | `pdf-text-extractor` → `type-classifier` → `content-router` | 90–97% |
| `financial-pipeline` | `invoice-parser` → `line-validator` → `totals-summarizer` | 95–99% |
| `code-review-pipeline` | `diff-parser` → `complexity-scorer` → `review-formatter` | 92–98% |

---

## Multi-provider support

BIBIVIDI works with any OpenAI-compatible API out of the box. Supported by default:

| Provider | Host | Notes |
|---|---|---|
| Anthropic | `api.anthropic.com` | Full support |
| OpenAI | `api.openai.com` | Full support |
| Google Gemini | `generativelanguage.googleapis.com` | Full support incl. `contents[]` format |
| Groq | `api.groq.com` | Free tier — quota savings mode |
| Mistral | `api.mistral.ai` | OpenAI-compatible |
| Together.ai | `api.together.xyz` | OpenAI-compatible |
| Ollama | `localhost:11434` | Requires `BIBIVIDI_ALLOW_LOCAL_APIS=true` |

**Free-tier / quota mode** — when `model_price_eur = 0` (Gemini free, Groq, Ollama),
BIBIVIDI switches framing from "€ saved" to "extra requests/day":

```
bibividi status
  Quota saved : +850 extra prompts/day within your Groq free tier
```

---

## BSS 1.1 — Skill chains

Chain multiple skills into a typed I/O pipeline. Each skill's output becomes
the next skill's input:

```bash
bibividi chain build   # scaffold a chain pack from installed skills
bibividi chain ...     # manage chains
```

Enable in config:
```env
BIBIVIDI_ENABLE_CHAINS=true
BIBIVIDI_MAX_CHAIN_DEPTH=10        # max skills in a chain
BIBIVIDI_MAX_CHAIN_RUNTIME_S=0     # 0 = 3× MAX_SCRIPT_RUNTIME_S
```

## BSS 2.0 — Auto-assembly

Automatically discovers and assembles typed I/O pipelines from installed skills
without manual chain definitions:

```env
BIBIVIDI_ENABLE_AUTO_ASSEMBLY=true
```

---

## HTTPS interception (optional)

For apps that send directly to `https://api.anthropic.com` without going through
the SDK integration above:

```bash
bibividi cert generate   # create local CA + server cert
bibividi cert install    # trust the CA (may require sudo)
bibividi start --ssl     # HTTP :8080 + HTTPS CONNECT tunnel :8443
```

Configure your HTTP client to use `http://127.0.0.1:8443` as a proxy:
```python
import httpx
client = httpx.Client(proxy="http://127.0.0.1:8443", verify="~/.bibividi/ca.crt")
```

---

## Auto-generate skills (generator)

When no script matches a prompt, BIBIVIDI calls the LLM once to generate
a new BSS skill automatically. The next similar request will be handled locally.
Generated skills are held for review until approved.

```env
BIBIVIDI_GENERATOR_ENABLED=true          # on by default
BIBIVIDI_GENERATOR_API_KEY=sk-ant-...    # key used only for generation
BIBIVIDI_GENERATOR_MODEL=claude-haiku-4-5-20251001
BIBIVIDI_GENERATOR_PROVIDER=anthropic    # anthropic|openai
```

Review and approve generated skills:
```bash
bibividi review          # list pending skills
bibividi approve <id>    # activate a skill for execution
```

---

## CLI reference

### Interactive shell (REPL)

Running `bibividi` with no arguments enters an interactive shell — no need to prefix every command:

```
$ bibividi
BIBIVIDI — AI token optimization proxy
Type help or ? for commands  ·  exit or Ctrl+D to quit

bibividi> start
Proxy started on 127.0.0.1:8080
Point your apps to http://127.0.0.1:8080  ·  'tail' to watch requests  ·  'stop' to stop

bibividi> status
BIBIVIDI Status
  Library : 3 scripts
  ...

bibividi> list
bibividi> tail
bibividi> stop
bibividi> exit
Bye!
```

| Shell command | Description |
|---|---|
| `start [--ssl]` | Start the proxy in the background (shell stays live) |
| `stop` | Stop the running proxy |
| `status` | Show proxy status and token savings |
| `list [--chains]` | List installed skills |
| `add <pack-dir>` | Install a BSS skill pack |
| `review` | List pending auto-generated skills |
| `approve <id>` | Activate a pending skill |
| `tail` | Stream live request events (Ctrl+C to return to shell) |
| `simulate <file>` | Dry-run against a request log |
| `calibrate [file]` | Tune the match threshold |
| `demo` | Run the built-in token savings demo |
| `digest [--now]` | Show weekly savings digest |
| `report` | CSRD AI Scope 3 emissions report |
| `roi` | Open ROI calculator in browser |
| `feedback bad <id>` | Flag a bad skill output |
| `activate <key>` | Activate a license key |
| `help` / `?` | List all commands |
| `exit` / Ctrl+D | Quit the shell |

Command history is persisted across sessions in `~/.bibividi/shell_history`.

### One-liner mode

All commands also work directly without entering the shell:

```bash
# Core
bibividi activate <license-key>     # activate your license (one-time)
bibividi start [--ssl] [--host HOST] [--port PORT]
bibividi status
bibividi list
bibividi add <pack-dir>
bibividi test <script-id>           # prompt via stdin
bibividi demo                       # in-process demo on a sample contract

# Certificates
bibividi cert generate|install|path

# Skill chains (BSS 1.1)
bibividi chain build

# Approval workflow (auto-generated skills)
bibividi review
bibividi approve <skill-id>

# Trust feedback
bibividi feedback ...               # flag bad skill outputs

# Observability
bibividi tail                       # stream live request events
bibividi calibrate [prompts-file]   # tune match threshold
bibividi simulate <requests-file>   # dry-run against a request log

# Reporting & billing
bibividi digest                     # weekly savings digest
bibividi digest-quarterly           # send quarterly email digest
bibividi report                     # CSRD AI Scope 3 emissions report
bibividi roi                        # open ROI calculator in browser
bibividi billing ...
bibividi marketplace ...
```

## Configuration

All settings via `BIBIVIDI_` environment variables (or `.env`):

| Variable | Default | Description |
|---|---|---|
| `BIBIVIDI_PROXY_PORT` | `8080` | Proxy listen port |
| `BIBIVIDI_TUNNEL_PORT` | `8443` | HTTPS CONNECT tunnel port |
| `BIBIVIDI_MATCH_THRESHOLD` | `0.75` | Cosine similarity threshold |
| `BIBIVIDI_MAX_SCRIPT_RUNTIME_S` | `10.0` | Sandbox timeout |
| `BIBIVIDI_DRY_RUN` | `false` | Log savings without injecting condensed result |
| `BIBIVIDI_SLACK_WEBHOOK` | — | Post savings alerts to Slack |
| `BIBIVIDI_GENERATOR_ENABLED` | `true` | Auto-generate skills on no-match |
| `BIBIVIDI_GENERATOR_MODEL` | `claude-haiku-4-5-20251001` | Model used for generation |
| `BIBIVIDI_GENERATOR_PROVIDER` | `anthropic` | `anthropic` or `openai` |
| `BIBIVIDI_ENABLE_CHAINS` | `false` | Enable BSS 1.1 skill chains |
| `BIBIVIDI_MAX_CHAIN_DEPTH` | `10` | Max skills per chain |
| `BIBIVIDI_ENABLE_AUTO_ASSEMBLY` | `false` | Enable BSS 2.0 auto-assembly |
| `BIBIVIDI_ALLOW_LOCAL_APIS` | `false` | Allow localhost targets (Ollama) |
| `BIBIVIDI_QUOTA_DAILY_TOKENS` | — | Override daily token quota for quota-mode display |
| `BIBIVIDI_BILLING_TIER` | `pro` | `free` \| `pro` \| `growth` \| `enterprise` |
| `BIBIVIDI_BILLING_API_URL` | — | URL of the billing/license API |
| `BIBIVIDI_LOG_REQUESTS` | `false` | Log prompt content (dev only) |

---

## Development

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

pytest                    # 294 tests
ruff check .
mypy bvd/

# Zero-credit local testing
uvicorn mock_api:app --port 9090 &
BIBIVIDI_TARGET_APIS='["localhost:9090"]' bibividi start
```

---

## Releasing

```bash
git tag v1.2.3
git push origin v1.2.3
```

This triggers two workflows automatically:
- **Release** — builds Tauri desktop installers (Linux `.AppImage`/`.deb`, macOS `.dmg`, Windows `.msi`) and creates a draft GitHub release
- **Publish to PyPI** — builds and publishes the Python package via OIDC trusted publishing

To publish the GitHub release, go to [Releases](https://github.com/bibividi/bibividi/releases), review the draft, and click **Publish release**.

---

## License

MIT — engine is open source. Cloud runner and marketplace are proprietary (Pro/Enterprise).
