Tako Python SDK

PyPI version

The Tako Python SDK provides convenient access to the Tako API from any Python 3.9+ application. It ships fully typed request and response models and offers both synchronous and asynchronous clients.

Documentation

API reference and guides are available at docs.tako.com.

Installation

pip install tako-sdk

The import package is tako:

from tako.lib import Tako

Authentication

Create an API key from your Tako account and provide it when building the client. We recommend keeping it out of source control — for example, reading it from an environment variable:

import os

from tako import Configuration
from tako.lib import Tako

config = Configuration()
config.api_key["apiKey"] = os.environ["TAKO_API_KEY"]
client = Tako(config)

Usage

import os

from tako import Configuration, SearchRequest
from tako.lib import Tako

config = Configuration()
config.api_key["apiKey"] = os.environ["TAKO_API_KEY"]
client = Tako(config)

results = client.search(SearchRequest(query="S&P 500 performance this year"))
print(results.request_id)
for card in results.cards or []:
    print(card.title, card.webpage_url)

Operations

Method Description
client.search(SearchRequest(...)) Search the Tako knowledge base; returns matching cards and web results.
client.answer(SearchRequest(...)) Get a written answer with supporting cards.
client.create_card(CreateCardRequest(...)) Build a visualization card from component configurations.
client.contents(ContentsRequest(...)) Fetch downloadable content (e.g. a CSV) for a card or web URL.

For example, fetch the underlying data for a card returned by a search. Not every card is exportable (some come from protected sources), so guard for the case where no card has downloadable content:

from tako import ContentsRequest, SearchRequest

results = client.search(SearchRequest(query="US Oil Prices"))
card = next(
    (c for c in (results.cards or []) if c.webpage_url and c.content and c.content.formats),
    None,
)
if card is None:
    print("No exportable card found")
else:
    contents = client.contents(ContentsRequest(url=card.webpage_url))
    for item in contents.contents or []:
        print(item.content_format, item.url)

Async usage

Use AsyncTako with the tako.aio package and await each call:

import asyncio
import os

from tako.aio import Configuration, SearchRequest
from tako.lib import AsyncTako


async def main() -> None:
    config = Configuration()
    config.api_key["apiKey"] = os.environ["TAKO_API_KEY"]
    client = AsyncTako(config)

    results = await client.search(SearchRequest(query="S&P 500 performance this year"))
    print(results.request_id)


asyncio.run(main())

The async client exposes the same operations as the synchronous one.

Agents

Two agent products hang off client.agent:

Namespace Endpoint Product
client.agent.retrieval.* /v1/agent/retrieval/runs Retrieval Agent — agentic data retrieval (multi-hop lookup, cohort resolution, structured outputs)
client.agent.answer.* /v1/agent/answer/runs Answer Agent — opinionated agentic research returning cited prose

Each exposes run(req) (202 dispatch → run object), get(run_id) (poll for status), and stream(req) (live SSE). (client.agent.answer.*, the Answer Agent, is distinct from client.answer(), the one-shot /v1/answer call.)

Streaming

Stream a run live over Server-Sent Events. The stream yields typed per-product envelopes (RetrievalAgentStreamEnvelope / AnswerAgentStreamEnvelope) and auto-reconnects (resuming via the last seq) on transient network drops. Use it as a context manager so the connection is always closed.

from tako import Configuration
from tako.lib import Tako
from tako.models.retrieval_agent_run_request import RetrievalAgentRunRequest

config = Configuration()
config.api_key["apiKey"] = "YOUR_API_KEY"
client = Tako(config)

req = RetrievalAgentRunRequest(query="Which S&P 500 semis grew revenue fastest in 2024?")
with client.agent.retrieval.stream(req) as stream:
    for event in stream:
        block = event.block.actual_instance
        print(event.seq, block.kind)
    # The stream ends at `stream_done`. If it ended without a terminal result
    # (and produced at least one event, so `run_id` is known), poll for status:
    if stream.result is None and stream.run_id is not None:
        run = client.agent.retrieval.get(stream.run_id)
        print(run.status)

Async usage mirrors this — stream = await client.agent.retrieval.stream(req) then async with stream: async for event in stream: .... The Answer Agent is identical with client.agent.answer.* and AnswerAgentRunRequest.

Structured output (Retrieval Agent)

Pass an output_schema (JSON Schema) to shape the response. Mark a property with "x-tako-dataset": true to request a dataset slot — filled with exact retrieved rows as a TakoDataset. Two helpers make this ergonomic:

  • derive_response_schema(schema) — the schema structured_output actually validates against (each slot becomes TakoDataset | null). Pair with jsonschema.
  • TakoDatasetView — a records / DataFrame view over a filled slot. .records needs no extra dependency; .to_dataframe() needs the pandas extra (pip install tako-sdk[pandas]).
import jsonschema
from tako.lib import Tako, TakoDatasetView, derive_response_schema
from tako.models.retrieval_agent_run_request import RetrievalAgentRunRequest

schema = {
    "type": "object",
    "properties": {
        "headline": {"type": "string"},
        "cohort": {"x-tako-dataset": True, "columns": ["company", "revenue"]},
    },
    "required": ["headline", "cohort"],
}

run = client.agent.retrieval.run(RetrievalAgentRunRequest(query="...", output_schema=schema))
run = client.agent.retrieval.get(run.run_id)  # poll to a terminal status

if run.result and run.result.structured_output:
    jsonschema.validate(run.result.structured_output, derive_response_schema(schema))
    view = TakoDatasetView(run.result.structured_output["cohort"])
    print(view.records)          # list[dict], one per row
    print(view.to_dataframe())   # typed pandas DataFrame (needs tako-sdk[pandas])

See examples/ for runnable scripts — sync (retrieval_agent_streaming.py, answer_agent_streaming.py, retrieval_agent_structured_output.py) and async (retrieval_agent_streaming_async.py, answer_agent_streaming_async.py).

Requests and responses

Request and response models are Pydantic models. Access fields as attributes (results.request_id), and use the usual helpers to serialize:

results.model_dump()        # -> dict
results.model_dump_json()   # -> JSON string

Configuration

By default the client targets the Tako production API. To point at a different host, pass it to Configuration:

from tako import Configuration

config = Configuration(host="https://staging.tako.com/api")

Handling errors

API errors raise a subclass of tako.ApiException. The exception carries the HTTP status, reason, and response body:

from tako import Configuration, SearchRequest
from tako.exceptions import ApiException, UnauthorizedException
from tako.lib import Tako

config = Configuration()
config.api_key["apiKey"] = "invalid-key"
client = Tako(config)

try:
    client.search(SearchRequest(query="US GDP growth rate"))
except UnauthorizedException:
    print("Invalid or missing API key")
except ApiException as exc:
    print(f"Request failed: {exc.status} {exc.reason}")
    print(exc.body)

The async client (AsyncTako) raises the same exception classes, so you can catch tako.exceptions.ApiException around await calls exactly as above — no async-specific imports are needed.

Status codes map to the following exception types (all subclasses of ApiException):

Status Code Exception
400 BadRequestException
401 UnauthorizedException
403 ForbiddenException
404 NotFoundException
409 ConflictException
422 UnprocessableEntityException
>=500 ServiceException

Versioning

This package follows SemVer. You can check the installed version at runtime:

import tako

print(tako.__version__)

Requirements

Python 3.9 or higher.

Support

Questions, bugs, or feedback? See the documentation at docs.tako.com.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.2.19)

Owner

PyPI data
Data sourced directly from PyPI's database.

Credits

Author: Tako

License

MIT License (MIT)

Requires

Python >=3.10

Provides Extra

pandas

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tako_sdk-2.2.7.tar.gz (149.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

tako_sdk-2.2.7-py3-none-any.whl (362.1 kB view details)

Uploaded Python 3

File details

Details for the file tako_sdk-2.2.7.tar.gz.

File metadata

  • Download URL: tako_sdk-2.2.7.tar.gz
  • Upload date:
  • Size: 149.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for tako_sdk-2.2.7.tar.gz
Algorithm Hash digest
SHA256 85feb49311b7bb3d7bbf1ebd0b2c12478af73c1daf8599e7dfac338617ebb95b
MD5 34bf9c8630d9fb16e692c583139ff4b4
BLAKE2b-256 1a98ac7999af48ca6cf75e2edb5e267c1b6e6f0218b6235b40a2a034d0f28ad5

See more details on using hashes here.

File details

Details for the file tako_sdk-2.2.7-py3-none-any.whl.

File metadata

  • Download URL: tako_sdk-2.2.7-py3-none-any.whl
  • Upload date:
  • Size: 362.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for tako_sdk-2.2.7-py3-none-any.whl
Algorithm Hash digest
SHA256 bb220ef7e1d102ae7767e9f39f2a05b89e6269c002afa675097efa2a15785b19
MD5 e72a1479e6ceece2123623ffc87a019c
BLAKE2b-256 4997bb5d3af5fea0ef3548edcb42b470946f73e85170aa4996caf9bae1a24d32

See more details on using hashes here.

Release history Release notifications | RSS feed

2.2.19

2 files

2.2.18

2 files

2.2.17

2 files

2.2.16

2 files

2.2.15

2 files

2.2.14

2 files

2.2.13

2 files

2.2.12

2 files

2.2.11

2 files

2.2.10

2 files

2.2.9

2 files

2.2.8

2 files

This release

2.2.7 This release

2 files

2.2.6

2 files

2.2.5

2 files

2.2.4

2 files

2.2.3

2 files

2.2.2

2 files

2.2.1

2 files

2.2.0

2 files

2.1.11

2 files

2.1.10

2 files

2.1.9

2 files

2.1.8

2 files

2.1.7

2 files

2.1.6

2 files

2.1.5

2 files

2.1.4

2 files

2.1.3

2 files

2.1.2

2 files

2.1.1

2 files

2.1.0

2 files

2.0.0

2 files

1.2.0

2 files

1.1.0

2 files

1.0.0

2 files

0.1.41

2 files

0.1.40

2 files

0.1.39

2 files

0.1.38

2 files

0.1.37

2 files

0.1.36

2 files

0.1.35

2 files

0.1.34

2 files

0.1.33

2 files

0.1.32

2 files

0.1.31

2 files

0.1.30

2 files

0.1.29

2 files

0.1.28

2 files

0.1.27

2 files

0.1.26

2 files

0.1.25

2 files

0.1.24

2 files

0.1.23

2 files

0.1.22

2 files

0.1.21

2 files

0.1.20

2 files

0.1.19

2 files

0.1.18

2 files

0.1.17

2 files

0.1.16

2 files

0.1.15

2 files

0.1.14

2 files

0.1.13

2 files

0.1.12

2 files

0.1.11

2 files

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page