cognigo 0.1.0

Python SDK for the Cognita document intelligence API: parse, export, chunk and store documents.

Cognigo — Python SDK

Python client for the Cognita document intelligence API: parse documents (PDF, DOCX, XLSX, PPTX, HTML, email, images) into a structured IR, export to markdown/text/HTML/JSON, split into retrieval-ready chunks for RAG, store documents server-side, and fetch page images.

The API surface this SDK wraps is described by the OpenAPI schema at cognita-new/openapischemas/openapi.yaml.

Install

pip install -e .

Requires Python 3.9+ and depends only on httpx.

Quick start

from cognigo import Cognita

client = Cognita("http://localhost:8080", api_key="your-api-key")

# Parse a document into markdown + metadata
result = client.parse("report.pdf", include=["markdown", "metadata"])
print(result.markdown)
print(result.metadata.title, result.metadata.page_count)

# Full IR
result = client.parse("report.pdf", include=["document"], omit_image_data=True)
doc = result.document
for page in doc.pages:
    for block in page.blocks:
        print(block.type, block.text[:60])

# Chunk for RAG (upload, or pass an already-parsed IR document)
chunks = client.chunk("report.pdf", max_chars=1500, overlap=150)
for chunk in chunks:
    print(chunk.heading_path, chunk.chars)

# Re-render an IR document without re-parsing
html = client.export(doc, "html")

# Thai (or any OCR) documents: override the OCR language set
result = client.parse("scan.png", languages="tha+eng")

Stored documents (parse once, use later)

summary = client.documents.store("report.pdf")

client.documents.list()                      # newest first
doc = client.documents.get(summary.id)       # full IR
md = client.documents.export(summary.id, "markdown")
chunks = client.documents.chunks(summary.id, max_chars=1000)
img = client.documents.page_image(summary.id, page=1, scale=2)
img.save("page1.png")
client.documents.delete(summary.id)

Async

Every method has an async twin on AsyncCognita:

from cognigo import AsyncCognita

async with AsyncCognita("http://localhost:8080", api_key="...") as client:
    result = await client.parse("report.pdf", include=["markdown"])
    chunks = await client.documents.chunks(doc_id)

File inputs

parse, chunk and documents.store accept a path (str/PathLike), raw bytes, or an open binary file object. Pass filename= to control the name recorded server-side when uploading bytes or file objects.

Errors

All errors derive from cognigo.CognitaError. Non-2xx API responses raise a subclass of cognigo.APIError with .status_code and .message:

Status	Exception
400	BadRequestError
401	AuthenticationError
404	NotFoundError
413	PayloadTooLargeError
415	UnsupportedFormatError (undetectable/unsupported format)
422	UnprocessableDocumentError (recognized but unparseable)
503	ServiceUnavailableError

from cognigo import Cognita, UnsupportedFormatError

try:
    client.parse("mystery.bin")
except UnsupportedFormatError as e:
    print(e.status_code, e.message)

Development

pip install -e ".[dev]"
pytest

Tests run against an in-process mock of the API (no server needed).