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.11.tar.gz (151.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.11-py3-none-any.whl (366.0 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: tako_sdk-2.2.11.tar.gz
  • Upload date:
  • Size: 151.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.11.tar.gz
Algorithm Hash digest
SHA256 cfe97021afc184127e41517eff310f4c9575bc1171de156795b6979234c3a032
MD5 c5286a8a0d745f0f9653c198067a03ab
BLAKE2b-256 cd7fc1d52fda55bf358e0b36204b2ee42ebb167b7778ac1a3bbd024a5e53091d

See more details on using hashes here.

File details

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

File metadata

  • Download URL: tako_sdk-2.2.11-py3-none-any.whl
  • Upload date:
  • Size: 366.0 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.11-py3-none-any.whl
Algorithm Hash digest
SHA256 3dec391a101f531fe0401d43eb3784577098b3b5c10f42f83a851ce3823cc0ea
MD5 833ccf771149ab17835b8212d53f56d6
BLAKE2b-256 db3d56f97f554c08d09659f0c0252bf77d107821a0d2df5769df7ad04cfa595e

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

This release

2.2.11 This release

2 files

2.2.10

2 files

2.2.9

2 files

2.2.8

2 files

2.2.7

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