tako-sdk 2.0.0

The official Python library for the tako API

Tako Python SDK

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:

from tako import ContentsRequest

card = next(c for c in (results.cards or []) if c.content and c.content.formats)
contents = client.contents(ContentsRequest(url=card.webpage_url))
for item in contents.contents or []:
    print(item.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.

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.