API Documentation

pip install gemina

import asyncio
from gemina import GeminaClient, UploadExtractionTypeEnum

async def main():
    async with GeminaClient("YOUR_API_KEY") as client:
        result = await client.process_document(
            "invoice.png",  # path, bytes, or a binary file object
            [UploadExtractionTypeEnum.INVOICE_HEADERS],
        )
        values = result.data.extractions[0].values
        print("Supplier:", values["vendorName"]["value"])
        print("Total:   ", values["totalAmount"]["value"], values["currency"]["value"])
        print("Date:    ", values["invoiceDate"]["value"])

asyncio.run(main())

from gemina import UploadExtractionTypeEnum

# Reuse a document_id from process_document, FileTag, or a document lookup.
updated = await client.add_extractions_and_wait(
    document_id,
    [UploadExtractionTypeEnum.INVOICE_LINE_ITEMS],
    include_coordinates=True,
)

print(updated.data.extractions)

# Submit-only generated surface (poll poll_correlation_id yourself):
# from gemina.generated.models.add_extractions_in_dto import AddExtractionsInDTO
# from gemina.generated.models.document_add_extractions_out_dto import DocumentAddExtractionsOutDTO
# submitted: DocumentAddExtractionsOutDTO = await client.documents.add_document_extractions(
#     document_id,
#     AddExtractionsInDTO(extraction_types=[UploadExtractionTypeEnum.INVOICE_LINE_ITEMS]),
# )

from gemina import GeminaClient, RetrievalQueryInDTO
from gemina.generated.models.retrieval_filters_dto import RetrievalFiltersDTO

async def search():
    async with GeminaClient("YOUR_API_KEY") as client:
        page = await client.retrieval.retrieval_query(RetrievalQueryInDTO(
            mode="hybrid",                 # structured | semantic | hybrid
            text="cleaning services",
            filters=RetrievalFiltersDTO(total_amount_min=100),
            top_k=5,
        ))
        for item in page.items:
            print(item.vendor_name, item.total_amount, item.currency,
                  item.issue_date, item.document_id)

from gemina import GeminaClient, RetrievalAggregateInDTO
from gemina.generated.models.aggregate_metric_dto import AggregateMetricDTO

async def totals_by_vendor():
    async with GeminaClient("YOUR_API_KEY") as client:
        report = await client.retrieval.retrieval_aggregate(RetrievalAggregateInDTO(
            metrics=[
                AggregateMetricDTO(op="sum", field="total_amount"),
                AggregateMetricDTO(op="count"),
            ],
            group_by=["vendor_name"],
        ))
        for row in report.rows:
            print(row.group, row.values["sum_total_amount"].actual_instance,
                  row.values["count"].actual_instance)

from gemina import GeminaClient, ChatQueryInDTO

async def ask():
    async with GeminaClient("YOUR_API_KEY") as client:
        reply = await client.chat.chat_query(ChatQueryInDTO(
            message="What is the total amount of my invoices from last month?",
        ))
        print(reply.answer)
        print("confident:", reply.confident)
        print("citations:", reply.citations)

async def conversation():
    async with GeminaClient("YOUR_API_KEY") as client:
        chat = client.conversation()
        await chat.send("How much did we spend on cleaning in 2020?")
        follow = await chat.send("And which vendor was most expensive?")  # remembers 2020 / cleaning
        print(follow.answer, "· session:", chat.session_id)

        await chat.delete()   # end it server-side (or chat.reset() to just forget it locally)

async def history():
    async with GeminaClient("YOUR_API_KEY") as client:
        listing = await client.chat.list_chat_sessions(limit=20)
        for session in listing.sessions:
            print(session.title, "·", session.turn_count, "turns")

        transcript = await client.chat.get_chat_session(listing.sessions[0].id)
        for msg in transcript.messages:
            print(f"[{msg.role}] {msg.content}")

        await client.chat.purge_chat_session(listing.sessions[0].id)

from gemina import GeminaClient, SessionTokenInDTO

async def mint_token():
    async with GeminaClient("YOUR_API_KEY") as client:  # server-side only
        token = await client.sessions.mint_retrieval_token(SessionTokenInDTO(
            end_user_id="customer-42",   # omit for a whole-account session
            ttl_seconds=600,             # clamped server-side to [300, 900]
        ))
        return token.token               # ship this to the frontend

from gemina import GeminaClient, SessionTokenInDTO
from gemina.generated.models.extraction_validation_in_dto import (
    ExtractionValidationInDTO,
)

async def mint_verification_token(extraction_id):
    """Server-side. Authorize the end-user against this id FIRST — Gemina
    enforces the claim, you decide who gets it."""
    async with GeminaClient("YOUR_API_KEY") as client:
        token = await client.sessions.mint_retrieval_token(SessionTokenInDTO(
            extraction_ids=[extraction_id],   # pins the token — up to 10
            ttl_seconds=900,
        ))
        return token.token                    # ship this to the browser

async def read_back(extraction_id):
    """The source of truth. The widget's browser callback is best-effort."""
    async with GeminaClient("YOUR_API_KEY") as client:
        view = await client.documents.get_document_extraction(extraction_id)

        if not view.meta.validated:
            return view.values                # nobody has reviewed it yet

        for change in view.verified_diff:     # corrected | added | removed
            print(change.status, change.field, change.original, "->", change.verified)
        return view.verified_values           # same shape as values, corrected

async def submit_without_the_widget(extraction_id, corrected_values):
    """Only if you build your own review UI. One-shot: a second call is a 409."""
    async with GeminaClient("YOUR_API_KEY") as client:
        return await client.documents.validate_document_extraction(
            extraction_id,
            ExtractionValidationInDTO(data=corrected_values),
        )

from gemina import GeminaError, GeminaProcessingError, GeminaTimeoutError

async def robust():
    async with GeminaClient("YOUR_API_KEY") as client:
        try:
            result = await client.process_document(
                "invoice.pdf",
                [UploadExtractionTypeEnum.INVOICE_HEADERS],
                timeout_seconds=120,
            )
        except GeminaProcessingError as exc:
            print("processing failed:", exc.result.errors)
        except GeminaTimeoutError as exc:
            print("still running, poll later:", exc.correlation_id)
            result = await client.documents.\
                get_document_processing_result_by_correlation_id(exc.correlation_id)

dotnet add package Gemina.Sdk

using Gemina.Sdk;
using Gemina.Sdk.Model;
using Newtonsoft.Json.Linq;

var client = new GeminaClient("YOUR_API_KEY");

var result = await client.ProcessDocumentAsync(
    GeminaDocumentSource.FromFile("invoice.png"),
    new List<UploadExtractionTypeEnum> { UploadExtractionTypeEnum.InvoiceHeaders });

var headers = result.Data.Extractions[0];
Console.WriteLine($"Status:   {result.Status}");
Console.WriteLine($"Supplier: {(headers.Values["vendorName"] as JObject)?["value"]}");
Console.WriteLine($"Total:    {(headers.Values["totalAmount"] as JObject)?["value"]}");
Console.WriteLine($"Date:     {(headers.Values["invoiceDate"] as JObject)?["value"]}");

// Reuse a documentId from ProcessDocumentAsync, FileTag, or a document lookup.
var updated = await client.AddExtractionsAndWaitAsync(
    documentId,
    new List<UploadExtractionTypeEnum>
    {
        UploadExtractionTypeEnum.InvoiceLineItems
    });

Console.WriteLine(updated.Data.Extractions.Count);

// Submit-only generated surface (poll PollCorrelationId yourself):
// DocumentAddExtractionsOutDTO submitted = await client.Documents
//     .AddDocumentExtractionsAsync(documentId, new AddExtractionsInDTO(
//         extractionTypes: new List<UploadExtractionTypeEnum>
//         {
//             UploadExtractionTypeEnum.InvoiceLineItems
//         }));

using Gemina.Sdk.Model;

var query = await client.Retrieval.RetrievalQueryAsync(new RetrievalQueryInDTO(
    text: "cleaning services invoices",
    topK: 5));

foreach (var item in query.Items)
{
    Console.WriteLine($"{item.VendorName} — {item.TotalAmount} {item.Currency} " +
                      $"(issued {item.IssueDate:d}, document {item.DocumentId})");
}

var aggregate = await client.Retrieval.RetrievalAggregateAsync(new RetrievalAggregateInDTO(
    metrics: new List<AggregateMetricDTO>
    {
        new AggregateMetricDTO(AggregateMetricDTO.FieldEnum.TotalAmount, AggregateMetricDTO.OpEnum.Sum),
    },
    groupBy: new List<RetrievalAggregateInDTO.GroupByEnum>
    {
        RetrievalAggregateInDTO.GroupByEnum.VendorName,
    }));

foreach (var row in aggregate.Rows)
{
    Console.WriteLine($"{row.Group["vendor_name"]}: {row.Values["sum_total_amount"].ActualInstance}");
}

var reply = await client.Chat.ChatQueryAsync(new ChatQueryInDTO(
    message: "How much did I spend on cleaning services this year?"));

Console.WriteLine(reply.Answer);
Console.WriteLine($"Confident: {reply.Confident}");
Console.WriteLine($"Citations: {string.Join(", ", reply.Citations ?? new List<string>())}");

var chat = client.Conversation();
await chat.SendAsync("How much did we spend on cleaning in 2020?");
var follow = await chat.SendAsync("And which vendor was most expensive?"); // remembers 2020 / cleaning
Console.WriteLine($"{follow.Answer} · session: {chat.SessionId}");

await chat.DeleteAsync(); // end it server-side (or chat.Reset() to just forget it locally)

var listing = await client.Chat.ListChatSessionsAsync(limit: 20);
foreach (var session in listing.Sessions)
    Console.WriteLine($"{session.Title} · {session.TurnCount} turns");

var transcript = await client.Chat.GetChatSessionAsync(listing.Sessions[0].Id);
foreach (var msg in transcript.Messages)
    Console.WriteLine($"[{msg.Role}] {msg.Content}");

await client.Chat.PurgeChatSessionAsync(listing.Sessions[0].Id);

var session = await client.Sessions.MintRetrievalTokenAsync(new SessionTokenInDTO(
    endUserId: "user-123",
    ttlSeconds: 900));

// Send session.Token to your frontend; it expires in session.ExpiresIn seconds.

var sessionClient = GeminaClient.WithSessionToken(session.Token);

// Server-side. Authorize the end-user against this id FIRST — Gemina enforces
// the claim in the signed token, you decide who gets it.
var session = await client.Sessions.MintRetrievalTokenAsync(new SessionTokenInDTO(
    extractionIds: new List<Guid> { extractionId },  // pins the token — up to 10
    ttlSeconds: 900));
// Ship session.Token to the browser and render <GeminaVerification />.

// The source of truth. The widget's browser callback is best-effort.
var view = await client.Documents.GetDocumentExtractionAsync(extractionId);

if (view.Meta.Validated == true)
{
    foreach (var change in view.VerifiedDiff)
    {
        // Status: corrected | added | removed
        Console.WriteLine($"{change.Status} {change.Field}: {change.Original} -> {change.Verified}");
    }
    UseThis(view.VerifiedValues);  // same shape as Values, corrections merged in
}
else
{
    UseThis(view.Values);          // nobody has reviewed it yet
}

// Only if you build your own review UI. One-shot: a second call is a 409.
var summary = await client.Documents.ValidateDocumentExtractionAsync(
    extractionId,
    new ExtractionValidationInDTO(data: correctedValues));

using Gemina.Sdk.Client;

try
{
    var result = await client.ProcessDocumentAsync(source, extractionTypes);
}
catch (GeminaProcessingException ex)
{
    Console.WriteLine($"Processing failed: {ex.Result.Errors?.Count} error(s)");
}
catch (GeminaTimeoutException ex)
{
    // Resume polling on your own schedule:
    var result = await client.GetProcessingResultAsync(ex.CorrelationId);
}
catch (ApiException ex)
{
    Console.WriteLine($"HTTP {ex.ErrorCode}: {ex.Message}");
}

<dependency>
    <groupId>co.gemina</groupId>
    <artifactId>gemina-sdk</artifactId>
    <version>0.15.0</version>
</dependency>

import java.io.File;
import java.util.Collections;
import java.util.Map;

import co.gemina.sdk.GeminaClient;
import co.gemina.sdk.GeminaDocumentSource;
import co.gemina.sdk.generated.model.DocumentProcessingResultOutDTO;
import co.gemina.sdk.generated.model.UploadExtractionTypeEnum;

public class Quickstart {
    public static void main(String[] args) throws Exception {
        GeminaClient client = new GeminaClient(System.getenv("GEMINA_API_KEY"));

        DocumentProcessingResultOutDTO result = client.processDocument(
                GeminaDocumentSource.fromFile(new File("invoice.pdf")),
                Collections.singletonList(UploadExtractionTypeEnum.INVOICE_HEADERS));

        System.out.println("status: " + result.getStatus());

        // Each value field is a map: {"value": ..., "confidence": ..., "coordinates": ...}
        Map<String, Object> values = result.getData().getExtractions().get(0).getValues();
        System.out.println("vendor: " + field(values, "vendorName"));
        System.out.println("total:  " + field(values, "totalAmount"));
        System.out.println("date:   " + field(values, "invoiceDate"));
    }

    @SuppressWarnings("unchecked")
    static Object field(Map<String, Object> values, String name) {
        Map<String, Object> f = (Map<String, Object>) values.get(name);
        return f == null ? null : f.get("value");
    }
}

import co.gemina.sdk.ProcessDocumentOptions;
import co.gemina.sdk.generated.model.AddExtractionsInDTO;
import co.gemina.sdk.generated.model.DocumentAddExtractionsOutDTO;

// Reuse a documentId from processDocument, FileTag, or a document lookup.
DocumentProcessingResultOutDTO updated = client.addExtractionsAndWait(
        documentId,
        Collections.singletonList(UploadExtractionTypeEnum.INVOICE_LINE_ITEMS),
        ProcessDocumentOptions.defaults());

System.out.println(updated.getData().getExtractions().size());

// Submit-only generated surface (poll getPollCorrelationId() yourself):
// DocumentAddExtractionsOutDTO submitted = client.documents()
//     .addDocumentExtractions(documentId, new AddExtractionsInDTO()
//         .extractionTypes(Collections.singletonList(
//             UploadExtractionTypeEnum.INVOICE_LINE_ITEMS)));

import co.gemina.sdk.generated.model.*;

RetrievalQueryOutDTO hits = client.retrieval().retrievalQuery(
        new RetrievalQueryInDTO()
                .text("cloud hosting invoices over 500 euro")
                .filters(new RetrievalFiltersDTO().currency("EUR"))
                .limit(10));

for (QueryResultItemDTO item : hits.getItems()) {
    System.out.println(item.getVendorName() + "  " + item.getTotalAmount()
            + "  " + item.getIssueDate() + "  (document " + item.getDocumentId() + ")");
}

RetrievalAggregateOutDTO totals = client.retrieval().retrievalAggregate(
        new RetrievalAggregateInDTO()
                .metrics(Collections.singletonList(new AggregateMetricDTO()
                        .op(AggregateMetricDTO.OpEnum.SUM)
                        .field(AggregateMetricDTO.FieldEnum.TOTAL_AMOUNT)))
                .groupBy(Collections.singletonList(RetrievalAggregateInDTO.GroupByEnum.VENDOR_NAME)));

for (AggregateRowDTO row : totals.getRows()) {
    System.out.println(row.getGroup() + " -> " + row.getValues());
}

ChatQueryOutDTO reply = client.chat().chatQuery(
        new ChatQueryInDTO().message("How much did we spend on hosting last quarter?"));

System.out.println(reply.getAnswer());
System.out.println("confident: " + reply.getConfident());
System.out.println("citations: " + reply.getCitations());

GeminaClient.GeminaChatConversation chat = client.conversation();
chat.send("How much did we spend on cleaning in 2020?");
ChatQueryOutDTO follow = chat.send("And which vendor was most expensive?"); // remembers 2020 / cleaning
System.out.println(follow.getAnswer() + " · session: " + chat.getSessionId());

chat.delete(); // end it server-side (or chat.reset() to just forget it locally)

ChatSessionListOutDTO listing = client.chat().listChatSessions(null, 20, null, null, null);
for (ChatSessionOutDTO session : listing.getSessions()) {
    System.out.println(session.getTitle() + " · " + session.getTurnCount() + " turns");
}

UUID sessionId = listing.getSessions().get(0).getId();
ChatTranscriptOutDTO transcript = client.chat().getChatSession(sessionId, null, null, null);
for (ChatMessageOutDTO msg : transcript.getMessages()) {
    System.out.println("[" + msg.getRole() + "] " + msg.getContent());
}

client.chat().purgeChatSession(sessionId);

SessionTokenOutDTO session = client.sessions().mintRetrievalToken(
        new SessionTokenInDTO()
                .endUserId("user-123")
                .ttlSeconds(900));

// Send session.getToken() to your frontend.
System.out.println(session.getToken() + " expires in " + session.getExpiresIn() + "s");

// Server-side. Authorize the end-user against this id FIRST — Gemina enforces
// the claim in the signed token, you decide who gets it.
SessionTokenOutDTO session = client.sessions().mintRetrievalToken(
        new SessionTokenInDTO()
                .extractionIds(Arrays.asList(extractionId))  // up to 10
                .ttlSeconds(900));
// Ship session.getToken() to the browser and render <GeminaVerification />.

// The source of truth. The widget's browser callback is best-effort.
ExtractionPrimaryViewOutDTO view = client.documents()
        .getDocumentExtraction(extractionId);

if (Boolean.TRUE.equals(view.getMeta().getValidated())) {
    for (VerifiedDiffEntryOutDTO change : view.getVerifiedDiff()) {
        // status: corrected | added | removed
        System.out.println(change.getStatus() + " " + change.getField()
                + ": " + change.getOriginal() + " -> " + change.getVerified());
    }
    useThis(view.getVerifiedValues());  // same shape as values, corrected
} else {
    useThis(view.getValues());          // nobody has reviewed it yet
}

// Only if you build your own review UI. One-shot: a second call is a 409.
ExtractionValidationResultOutDTO summary = client.documents()
        .validateDocumentExtraction(
                extractionId,
                new ExtractionValidationInDTO().data(correctedValues));

try {
    DocumentProcessingResultOutDTO result = client.processDocument(source, types, options);
} catch (GeminaProcessingException e) {
    System.err.println("processing failed: " + e.getResult().getErrors());
} catch (GeminaTimeoutException e) {
    UUID correlationId = e.getCorrelationId(); // resume polling with this
    DocumentProcessingResultOutDTO last = client.documents()
            .getDocumentProcessingResultByCorrelationId(correlationId);
} catch (ApiException e) {
    System.err.println("HTTP " + e.getCode() + ": " + e.getResponseBody());
}

composer require gemina/sdk

<?php

require 'vendor/autoload.php';

use Gemina\Sdk\GeminaClient;

$client = new GeminaClient(getenv('GEMINA_API_KEY'));

$result = $client->processDocument('invoice.png', ['invoice_headers']);

echo 'Status: ', $result->getStatus(), PHP_EOL;

$extraction = $result->getData()->getExtractions()[0];
$values = $extraction->getValues();

// Each field is an object with ->value (plus ->coordinates and ->confidence when available)
echo 'Supplier: ', $values['vendorName']->value ?? 'n/a', PHP_EOL;
echo 'Total:    ', $values['totalAmount']->value ?? 'n/a', PHP_EOL;
echo 'Date:     ', $values['invoiceDate']->value ?? 'n/a', PHP_EOL;

// Reuse a document ID from processDocument(), FileTag, or a document lookup.
$updated = $client->addExtractionsAndWait(
    $documentId,
    ['invoice_line_items'],
    ['includeCoordinates' => true],
);

echo count($updated->getData()->getExtractions()), PHP_EOL;

// Submit-only generated surface (poll getPollCorrelationId() yourself):
// $submitted = $client->documents()->addDocumentExtractions(
//     $documentId,
//     new AddExtractionsInDTO(['extraction_types' => ['invoice_line_items']]),
// ); // DocumentAddExtractionsOutDTO

use Gemina\Sdk\Model\RetrievalQueryInDTO;

$out = $client->retrieval()->retrievalQuery(new RetrievalQueryInDTO([
    'text' => 'cloud hosting invoices from June',
    'top_k' => 10,
]));

foreach ($out->getItems() as $item) {
    printf(
        "%s | %s | %s %s\n",
        $item->getDocumentId(),
        $item->getVendorName(),
        $item->getTotalAmount(),
        $item->getCurrency(),
    );
}

use Gemina\Sdk\Model\AggregateMetricDTO;
use Gemina\Sdk\Model\RetrievalAggregateInDTO;

$agg = $client->retrieval()->retrievalAggregate(new RetrievalAggregateInDTO([
    'metrics' => [new AggregateMetricDTO(['op' => 'sum', 'field' => 'total_amount'])],
    'group_by' => ['vendor_name'],
]));

foreach ($agg->getRows() as $row) {
    print_r($row->getGroup());
    print_r($row->getValues());
}

use Gemina\Sdk\Model\ChatQueryInDTO;

$chat = $client->chat()->chatQuery(new ChatQueryInDTO([
    'message' => 'How much did I spend on hosting in June, and with which vendor?',
]));

echo $chat->getAnswer(), PHP_EOL;
echo 'Confident: ', $chat->getConfident() ? 'yes' : 'no', PHP_EOL;
print_r($chat->getCitations());

$chat = $client->conversation();
$chat->send('How much did I spend on hosting in June, and with which vendor?');
$follow = $chat->send('And which month was cheapest?'); // remembers hosting / June
printf("%s · session: %s\n", $follow->getAnswer(), $chat->getSessionId());

$chat->delete(); // end it server-side (or $chat->reset() to just forget it locally)

$listing = $client->chat()->listChatSessions(0, 20);
foreach ($listing->getSessions() as $session) {
    printf("%s · %d turns\n", $session->getTitle(), $session->getTurnCount());
}

$sessionId = $listing->getSessions()[0]->getId();
$transcript = $client->chat()->getChatSession($sessionId);
foreach ($transcript->getMessages() as $msg) {
    printf("[%s] %s\n", $msg->getRole(), $msg->getContent());
}

$client->chat()->purgeChatSession($sessionId);

use Gemina\Sdk\Model\SessionTokenInDTO;

$token = $client->sessions()->mintRetrievalToken(new SessionTokenInDTO([
    'end_user_id' => 'user-42',
    'ttl_seconds' => 900,
]));

echo $token->getToken(); // pass to the frontend

use Gemina\Sdk\Model\SessionTokenInDTO;
use Gemina\Sdk\Model\ExtractionValidationInDTO;

// Server-side. Authorize the end-user against this id FIRST — Gemina enforces
// the claim in the signed token, you decide who gets it.
$token = $client->sessions()->mintRetrievalToken(new SessionTokenInDTO([
    'extraction_ids' => [$extractionId],  // pins the token — up to 10
    'ttl_seconds' => 900,
]));
// Ship $token->getToken() to the browser and render <GeminaVerification />.

// The source of truth. The widget's browser callback is best-effort.
$view = $client->documents()->getDocumentExtraction($extractionId);

if ($view->getMeta()->getValidated()) {
    foreach ($view->getVerifiedDiff() as $change) {
        // status: corrected | added | removed
        printf("%s %s: %s -> %s\n", $change->getStatus(), $change->getField(),
            $change->getOriginal(), $change->getVerified());
    }
    useThis($view->getVerifiedValues());  // same shape as values, corrected
} else {
    useThis($view->getValues());          // nobody has reviewed it yet
}

// Only if you build your own review UI. One-shot: a second call is a 409.
$summary = $client->documents()->validateDocumentExtraction($extractionId,
    new ExtractionValidationInDTO(['data' => $correctedValues]));

use Gemina\Sdk\ApiException;
use Gemina\Sdk\GeminaProcessingException;
use Gemina\Sdk\GeminaTimeoutException;

try {
    $result = $client->processDocument('invoice.png', ['invoice_headers']);
} catch (GeminaProcessingException $e) {
    // Terminal "failed" — the full result is attached
    print_r($e->getResult()->getErrors());
} catch (GeminaTimeoutException $e) {
    echo 'Still processing: ', $e->getCorrelationId(), PHP_EOL;
} catch (ApiException $e) {
    // Transport/HTTP errors from the generated client pass through unwrapped
    echo $e->getCode(), ': ', $e->getResponseBody(), PHP_EOL;
}