Python SDK

The Python SDK needs Python 3.9 or newer and returns typed models. The source is at github.com/yggy-tech/yggy-sdk-python.

Install

The PyPI release of yggy is coming soon. Until then, install the tagged release from GitHub:

pip install git+https://github.com/yggy-tech/[email protected]

Authenticate

Create an API key in yggy under Developers → API keys and keep it in the YGGY_API_KEY environment variable. A key that belongs to one organization needs nothing else. A personal key can see several organizations, so name the one you want in the x-yggy-organization-id header, by id or slug, as the examples do. See Authentication for key types and permissions.

Make your first call

List the projects your key can see:

import os

import yggy

configuration = yggy.Configuration(
    host="https://api.yggy.tech",
    api_key={"apiKeyAuth": os.environ["YGGY_API_KEY"]},
)

with yggy.ApiClient(configuration) as api_client:
    api_client.set_default_header("x-yggy-organization-id", "acme-corp")
    response = yggy.ProjectsApi(api_client).list_projects()
    for project in response.projects:
        print(project.name)

Each group of operations has its own class, for example ProjectsApi, DocumentsApi and QueryApi. Method and field names use snake_case.

Upload, wait and read the facts

This sample uploads Q4-report.pdf to project 0xproject, waits until extraction finishes, prints the extracted facts and asks a question. See Upload and extract for what each step returns.

import os
import time

import yggy

configuration = yggy.Configuration(
    host="https://api.yggy.tech",
    api_key={"apiKeyAuth": os.environ["YGGY_API_KEY"]},
)
project_id = "0xproject"

with yggy.ApiClient(configuration) as api_client:
    api_client.set_default_header("x-yggy-organization-id", "acme-corp")
    documents = yggy.DocumentsApi(api_client)

    with open("Q4-report.pdf", "rb") as f:
        upload = documents.upload_document(project_id, file=("Q4-report.pdf", f.read()), title="Q4 report.pdf")

    status = documents.get_document_status(project_id, upload.document_id)
    while not status.completed and not status.failed:
        time.sleep(2)
        status = documents.get_document_status(project_id, upload.document_id)
    if status.failed:
        raise RuntimeError(status.error or "Extraction failed")

    for t in documents.list_document_triples(project_id, upload.document_id).triples:
        print(t.subject, t.predicate, t.object)

    request = yggy.QueryProjectRequest(question="Which contracts renew in Q1?")
    print(yggy.QueryApi(api_client).query_project(project_id, query_project_request=request).answer)

Handle errors

A call that gets an error status raises yggy.exceptions.ApiException, or a subclass such as NotFoundException or UnauthorizedException. Read status first, then body for the error code.

from yggy.exceptions import ApiException

try:
    yggy.ProjectsApi(api_client).list_projects()
except ApiException as error:
    print(error.status, error.body)
    raise

See Errors and rate limits for the codes and for 429 handling. Honour the Retry-After header before you retry.

Next steps

• Reference for every operation and field.
• Authentication for key types and permissions.
• Webhooks to react to events instead of polling.