Metadata-Version: 2.4
Name: fissionbox
Version: 0.3.9
Summary: Fission box is a Python library built by NormAI to help you interact with the FissionBox API.
Author-email: Mohammad Alshakoush <mo@normai.nl>, Mo Assaf <assaf@normai.nl>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.11.7
Requires-Dist: requests>=2.32.4
Requires-Dist: rich>=13.0.0
Requires-Dist: tqdm>=4.67.1
Dynamic: license-file

# FissionBox SDK & CLI

Python SDK and command-line interface for the [FissionBox](https://www.beta.platform.fissionbox.ai) document intelligence platform.

## Installation

```bash
pip install fissionbox
```

## Authentication

```bash
# Log in via browser (Google OAuth)
fissionbox auth login

# Check current auth status
fissionbox auth status

# Log out
fissionbox auth logout
```

Credentials are stored in `~/.fissionbox/config.json`. Host overrides are environment-only and never persisted.

## Quickstart

```bash
# 1. Log in
fissionbox auth login

# 2. Set your default workspace
fissionbox namespace use --namespace-id ns-abc123

# 3. Queue documents for processing (with live status table)
#    Pass individual files, a folder, or both.
fissionbox document queue \
    --path ./invoices/ \
    --path extra.pdf \
    --extract-images \
    --output-dir ./fissionbox-output

# Results download automatically when processing finishes.
```

## Document Commands

### Queue (async — recommended for batches)

Upload and queue one or more documents for async processing. The command runs three phases automatically:

1. **Upload** — progress bar with filename, file size, count (`3/5`), and elapsed time
2. **Watch** — live table polling every 5 s showing status, elapsed time, chunk/image counts, and available artifacts per document
3. **Download** — progress bar across all files, then a file-tree view per document showing each artifact and its size

Results download automatically when processing finishes. Pass `--no-watch` to skip watching and downloading.

```bash
# Queue individual files
fissionbox document queue \
    --path invoice_jan.pdf \
    --path invoice_feb.pdf \
    --path report.docx \
    --schema-file schema.json \
    --extract-images \
    --output-dir ./fissionbox-output

# Queue an entire folder — every supported file becomes its own document run
fissionbox document queue \
    --path ./invoices/ \
    --extract-images \
    --output-dir ./fissionbox-output

# Mix files and folders
fissionbox document queue \
    --path ./invoices/ \
    --path ./contracts/ \
    --path one-off.pdf \
    --output-dir ./fissionbox-output
```

Supported file types: `.pdf`, `.docx`, `.png`, `.jpg`, `.jpeg`. Folders are expanded recursively.

Options:

| Flag | Default | Description |
|---|---|---|
| `--path PATH` | required | File or folder (repeat for multiple; folders expand recursively) |
| `--schema-file FILE` | — | JSON schema for structured data extraction |
| `--schema-json JSON` | — | Inline extraction schema as JSON string |
| `--extract-diagrams` | off | Extract diagrams |
| `--extract-images` | off | Extract images |
| `--response-detail` | `full` | `full` or `extracted_only` |
| `--queue-output FILE` | `fissionbox-queue.json` | Save queue state for `watch`/`download` |
| `--no-watch` | off | Skip watching and downloading after queue |
| `--output-dir DIR` | `./fissionbox-output` | Download destination |

### Watch

Live-polls document status with a rich table (ID, name, file, status, elapsed, chunks, images, available artifacts). Downloads all artifacts automatically when every document finishes. Pass `--no-download` to skip the download step.

```bash
# From a queue file (downloads to ./fissionbox-output by default)
fissionbox document watch \
    --queue-file fissionbox-queue.json \
    --output-dir ./fissionbox-output

# From explicit document IDs
fissionbox document watch \
    --id art-abc123 \
    --id art-def456

# Watch only — no download
fissionbox document watch \
    --queue-file fissionbox-queue.json \
    --no-download
```

### Download

Downloads all artifacts for processed documents with a progress bar and a per-document file-tree view showing each file and its size.

```bash
fissionbox document download \
    --queue-file fissionbox-queue.json \
    --output-dir ./fissionbox-output
```

Each document gets its own folder:

```
./fissionbox-output/
  invoice_jan/
    response.json     ← full extraction response
    markdown.md       ← document text as Markdown
    extracted.json    ← structured fields (if schema used)
    chunks.ndjson     ← text chunks for RAG / vector stores
    images/           ← extracted images
    annotated.pdf     ← annotated PDF (if annotation run)
  invoice_feb/
    …
```

### Single-file run (synchronous)

Upload and process a single document in one step. Blocks until the result is ready.

```bash
fissionbox document run \
    --path invoice.pdf \
    --schema-file schema.json \
    --extract-images
```

### Other document commands

```bash
# List all documents in the namespace
fissionbox document list --size 20

# Upload files without processing
fissionbox document upload --path ./invoices/

# Process a previously uploaded file
fissionbox document process \
    --source-path documents/source/invoice.pdf \
    --schema-file schema.json

# Generate an annotated PDF for a processed document
fissionbox document annotate --id art-abc123 --detail all

# Retry a failed document run
fissionbox document retry --id art-abc123

# Export text chunks as NDJSON (for RAG / embedding pipelines)
fissionbox document export-chunks --id art-abc123 --output ./chunks.ndjson
```

## Service Accounts (CI / automation)

```bash
# Create a service account
fissionbox account create-service-account --name document-bot

# List service accounts
fissionbox account list-service-accounts

# Issue a long-lived token (30 days)
fissionbox account issue-token \
    --service-account-id acc-abc123 \
    --max-age 2592000
```

Use the token in CI:

```bash
export FISSIONBOX_PLATFORM_API_KEY=<service-account-token>
export FISSIONBOX_NAMESPACE_ID=ns-abc123
fissionbox document queue --path report.pdf
```

## Python SDK

```python
from fissionbox.cli.utils.env import (
    get_document_client,
    get_idp_client,
    get_asset_client,
    resolve_namespace_id,
)

namespace_id = resolve_namespace_id(None)        # reads FISSIONBOX_NAMESPACE_ID or config
doc_client   = get_document_client(namespace_id)
idp_client   = get_idp_client()
asset_client = get_asset_client()

# Upload
source_path = doc_client.upload(namespace_id, "invoice.pdf")

# Queue async batch (mirrors the platform UI)
result = idp_client.queue_batch(
    namespace_id=namespace_id,
    source_paths=[source_path],
    extract_images=True,
)
doc_id = result["items"][0]["document_id"]

# Poll status
doc = doc_client.get(namespace_id, doc_id)
print(doc["metadata"]["status"])   # queued | processing | ready | failed

# Download a result asset
asset_client.download(
    namespace_id,
    doc["metadata"]["responsePath"],
    "./output/response.json",
)

# Generate annotated PDF
annotation = idp_client.annotate_stored(namespace_id, doc_id, detail="all")
asset_client.download(namespace_id, annotation["annotated_pdf_path"], "./output/annotated.pdf")
```

See `examples/` for complete working scripts:

| File | What it shows |
|---|---|
| `01_login.py` | Auth status check |
| `02_process_single_pdf.py` | Single-PDF pipeline — upload, process, annotated PDF, images |
| `03_queue_and_watch.py` | Async batch queue with rich live table and organized downloads |
| `04_cli_quickstart.sh` | Full CLI walkthrough |

## Environment Variables

| Variable | Description |
|---|---|
| `FISSIONBOX_PLATFORM_USER_TOKEN` | User access token (set by `fissionbox auth login`) |
| `FISSIONBOX_PLATFORM_API_KEY` | Service account API key |
| `FISSIONBOX_NAMESPACE_ID` | Default namespace ID |
| `FISSIONBOX_PLATFORM_HOST` | Platform API base URL |
| `FISSIONBOX_HOST` | FissionBox API base URL |

Defaults for production:

```text
FISSIONBOX_PLATFORM_HOST=https://api.beta.platform.fissionbox.ai
FISSIONBOX_HOST=https://api.beta.fissionbox.ai
```
