fissionbox 0.4.0

Fission box is a Python library built by NormAI to help you interact with the FissionBox API.

FissionBox SDK & CLI

Python SDK and command-line interface for the FissionBox document intelligence platform.

Installation

pip install fissionbox

Authentication

# 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

# 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.

# 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.

# 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.

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.

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

Other document commands

# 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

# Get the stored conversion response for a processed document
fissionbox document response --id art-abc123
fissionbox document response --id art-abc123 --format summary
fissionbox document response --id art-abc123 --output ./response.json

# Generate an annotated PDF for a processed document
fissionbox document annotate --id art-abc123 --detail all
fissionbox document annotate --id art-abc123 --download ./annotated.pdf
fissionbox document annotate --id art-abc123 --open
fissionbox document annotate --id art-abc123 --if-missing --download ./annotated.pdf

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

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

Service Accounts (CI / automation)

# 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:

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

Python SDK

from fissionbox.cli.utils.env import (
    get_document_client,
    get_idp_client,
    get_idp_client_via_fissionbox,
    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)

# Platform IDP endpoints (direct platform API)
idp_client   = get_idp_client()

# FissionBox-routed IDP endpoints (through fissionbox service)
idp_client   = get_idp_client_via_fissionbox(namespace_id)

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:

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