Metadata-Version: 2.4
Name: bbi-bucky
Version: 1.3.7
Summary: BBI Bucky — pluggable AI chatbot framework for enterprise applications
Author-email: BBI Engineering <engineering@bbi.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/bbi-engineering/bbi-bucky-framework
Project-URL: Documentation, https://github.com/bbi-engineering/bbi-bucky-framework#readme
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0
Provides-Extra: bedrock
Requires-Dist: boto3>=1.28.0; extra == "bedrock"
Provides-Extra: cortex
Requires-Dist: aiohttp>=3.8.0; extra == "cortex"
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: ruamel
Requires-Dist: ruamel.yaml>=0.17.0; extra == "ruamel"
Provides-Extra: api
Requires-Dist: fastapi>=0.100.0; extra == "api"
Requires-Dist: uvicorn>=0.23.0; extra == "api"
Provides-Extra: chromadb
Requires-Dist: chromadb>=0.4.0; extra == "chromadb"
Provides-Extra: scan
Requires-Dist: gitingest>=0.1.0; extra == "scan"
Provides-Extra: agent
Requires-Dist: mcp<2.0,>=1.0; extra == "agent"
Requires-Dist: langgraph>=1.0; extra == "agent"
Requires-Dist: langgraph-checkpoint-sqlite>=3.1; extra == "agent"
Requires-Dist: httpx>=0.24; extra == "agent"
Requires-Dist: jsonschema>=4.0; extra == "agent"
Provides-Extra: attachments
Requires-Dist: pypdf<7,>=5; extra == "attachments"
Requires-Dist: python-docx<2,>=1.1; extra == "attachments"
Provides-Extra: laya
Requires-Dist: laya>=0.4.2; extra == "laya"
Provides-Extra: all
Requires-Dist: bbi-bucky[agent,api,attachments,bedrock,chromadb,cortex,ruamel,scan,yaml]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: httpx>=0.24; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# bbi-bucky 1.3.7

Bucky adds an application assistant to supported FastAPI projects with a web frontend. The package generates the integration through `init` and `scan`; it does not require hand editing the host application for supported layouts.

## Install and run

```bash
python -m pip install 'bbi-bucky[api,agent,scan,chromadb,yaml,bedrock,attachments]'
bbi-bucky init --project-dir /path/to/application
bbi-bucky scan --project-dir /path/to/application --setup-deps
bbi-bucky doctor --project-dir /path/to/application
```

Set the LLM provider and model in `config/bucky.yaml` after `init`. Use `--smart` on `scan` to refine wording from screened documentation with the configured LLM. Both scan modes generate the same route integration, tool manifest, and widget. If the application does not keep an `openapi.json` file, the scanner infers simple routes and payloads from AST. For complex operations, start the app locally and pass `--openapi-url http://127.0.0.1:8000/openapi.json` to `scan`. This URL is restricted to localhost. `doctor` is read only and reports which operations were verified or skipped. `scan --dry-run` previews file changes.

`init` creates:

- `bucky.yaml`: LLM provider, mode settings, prompt, and retrieval config.
- `bucky_policy.yaml`: editable excluded paths, masked fields, and denied rows. Credential and environment-file exclusions are mandatory.
- `bucky_knowledge.md`: editable application guidance.
- A Bucky FastAPI route when a supported routes directory exists.

`scan` updates the generated route and configuration, writes `bucky_manifest.json`, indexes screened guidance in `.bucky_chromadb`, adds the packaged widget asset, and mounts the route and widget in supported FastAPI/Next.js or shared HTML entrypoints. It refreshes the manifest and widget on later scans. When the host has an application role map, the CLI shows proposed Bucky route grants and asks for Y/N before applying them; `--yes` accepts these grants for automated installations. Existing non-generated application code is patched only at recognized entrypoints; `doctor` reports unresolved operations. Keep generated files under review when upgrading an older installation.

The widget now keeps its open state during page navigation, shows navigation as a simple page result, and puts Agent, Plan, and file attachment controls in the composer `+` menu. The planner asks one application-specific question at a time and offers choices when it can derive them from the scanned operations. Attachments are limited to three files of 2 MB each (`.txt`, `.md`, `.csv`, `.json`, `.pdf`, `.docx`); PDF and DOCX parsing require the `attachments` extra. The server extracts and masks content locally, stores screened text for one hour under the current user session, and never stores uploaded bytes. Review `config/bucky_policy.yaml` for your application's sensitive fields and rows before accepting attachments.

For a supported FastAPI host that commits an OpenAPI snapshot and typed TypeScript client, `scan` recognizes its existing `api.openapi_dump` and `openapi-typescript` generators and synchronizes those files after mounting Bucky. `--setup-deps` offers to install declared Python requirements and npm lockfile dependencies before scanning; use `--yes` for an approved noninteractive installation. Unknown generators are left unchanged and reported for adapter work. No application source file needs hand editing.

## Governance and discovery

GitIngest inventories a temporary local copy of screened files. Environment files, credential paths, private keys, secrets, dependency folders, and generated assets are excluded before GitIngest reads them. AST analysis checks FastAPI route decorators locally. An OpenAPI contract supplies path, query, and JSON body schemas when available; otherwise a conservative AST adapter infers simple primitive and Pydantic payloads. A tool is enabled only when its route and payload are verified. Unsupported bodies, custom required headers, duplicate operation IDs, and uncertain routes are skipped and reported. The manifest records frontend screens, tool schemas, and declared OpenAPI permission schemes. Actual authorization remains with the host API under the current user session.

Only screened user guides and generated application guidance go into ChromaDB. Repository source is neither placed in the chat index nor sent to an external model. The default `local_hash` embedding runs offline. `--smart` sends screened documentation summaries to the configured LLM; it does not change the verified tool contract. The policy masks data before model input, model output, MCP results, and widget display. Keep sensitive application-specific fields and row rules current in `bucky_policy.yaml`.

## Agent and Plan

- **Agent** is the default mode for both conversation and action. The LLM chooses whether to answer from approved guidance, request a live read for additional context, or use verified application tools. Reads and navigation can run automatically. A proposed write displays its exact plan and waits for **Implement**. The LLM writes conversational replies; the package validates tool schemas, permissions, and action boundaries in code.
- **Plan** handles complex requests by asking the LLM to choose from verified tools. It displays up to ten operations with targets, exact inputs, reasons, and expected results without acting. **Implement** switches to Agent and authorizes only that displayed plan. Schema validation and policy checks run before a plan is saved.

A digest binds approval to the displayed actions. Bucky calls the generated MCP server over stdio; its wrappers invoke existing host API endpoints with the current session credentials. The host API enforces user and row permissions. Responses are masked, recorded in a metadata-only audit log, streamed as result cards, and linked to existing application screens. If a write was interrupted after starting, Bucky reports an uncertain outcome and never retries it automatically.

Plan state and LangGraph checkpoints are stored in permission-restricted SQLite files next to the Bucky config. The generated FastAPI integration exposes plan, implement, and resume routes. Changes to action inputs require a new plan. No shell or repository-write tool is exposed. The first agent stage acts through verified APIs and navigates existing pages; it does not click arbitrary browser controls or generate new screens.

When an action is underspecified, planning asks for the missing details and carries the recent conversation into the next turn. A plan can bind a later action's argument to an earlier tool response with `{"$from_step":0,"path":"/data/id"}`. Bucky validates the resulting concrete payload before execution and authorizes only that exact MCP call. Completed result cards are restored from the authenticated principal's plan store after navigation; the browser keeps no tool result data in session storage. Hosts with a shared preview token do not have distinct user identities and must provide real host authentication for per-user isolation. Root-level Vite/CRA HTML shells and literal React Router paths are recognized as frontend entrypoints. Backend route generation remains FastAPI-specific.

For a separate MCP client, run `bbi-bucky mcp-serve --project-dir /path/to/application --base-url http://127.0.0.1:8000`. This stdio server exposes discovered tools; writes remain blocked unless invoked through an exact approved Bucky plan.

The embedded MCP client starts a local stdio server process for tool calls. The wrapper calls the application's existing HTTP API at `BBI_BUCKY_HOST_API_URL` when set, otherwise at the current FastAPI server address. This works in a local process, Docker container, or EKS pod when Bucky can reach that API URL and the current user's authentication reaches the Bucky route. The package does not launch the host application, provision containers, or deploy Kubernetes services. It does not currently expose a remotely hosted MCP endpoint; keep the stdio server within the Bucky runtime.

## Frontend

The embedded widget uses the BBI Config palette: navy `#003d59`, orange `#fe6625`, and white surfaces. Its default size is 620 × 720 pixels. It renders Markdown tables in chat, exact plan steps, structured tool result cards, and existing-screen navigation. The widget sends the current page title, path, and headings with questions. Applications can publish additional selected-record state through `BbiBucky.publishPageContext()` or `contextExtractor`; this state is masked before it reaches the model.

## Development and release gates

From `packages/core`, run `python -m pytest tests`. From `packages/widget`, run `npm run typecheck && npm run build:all`, then copy `dist/bucky-embed.min.js` to `packages/core/bbi_bucky/assets/` before building the Python wheel. Validate both deterministic and `--smart` scans from the built wheel against a clean host app, including masking, role and row restrictions, exact payloads, interrupted writes, and navigation. Publish a stage only after its end-to-end package test passes without host hand edits.

The optional Laya decision adapter is included for offline evaluation and remains disabled in production routing. Install `bbi-bucky[laya]` only to benchmark it. A labeled JSONL file contains `query`, `app_name`, `tools`, `scope`, `retrieve`, and `tool` fields; run `bbi-bucky benchmark-routing --dataset labels.jsonl --adapter deterministic` and repeat with `--adapter laya`. Enable Laya for tool shortlisting and retrieval routing only after its labeled accuracy and latency beat deterministic routing on the target application. Permissions, masking, and plan authorization stay in code. Hosted Jev will require explicit opt-in and screened input. Deep-agent delegation and parallel execution remain gated behind production single-agent tests.

## Requirements

Python 3.11 or newer. FastAPI plus a web frontend is the automatic backend target. Next.js and shared HTML shells, including Vite/CRA at the repository root, are recognized frontend targets. Other backend stacks still require stack-specific integration work before automatic installation can be claimed.

## License

MIT
