tako

# Tako Knowledge Search & Visualization

Search for data with natural language and get interactive charts, AI-generated insights, and embeddable knowledge cards. Covers finance, economics, demographics, sports, politics, climate, and health from sources like S&P Global, World Bank, and more.

## When to Use

- User asks a data question ("What's NVIDIA's revenue?", "US GDP growth?")
- User wants to compare metrics ("Tesla vs Ford market cap")
- User needs a chart or visualization for a report
- User wants to turn their own data into a chart
- User asks for insights or analysis on a data trend

## Usage

### Search for Data

```bash
orth run tako /v1/knowledge_search -b '{"inputs": {"text": "NVIDIA vs AMD revenue since 2018"}}'
```

With search effort and source options:

```bash
orth run tako /v1/knowledge_search -b '{"inputs": {"text": "US inflation rate 2020-2025", "search_effort": "deep"}, "source_indexes": ["tako", "web"]}'
```

With dark mode chart images:

```bash
orth run tako /v1/knowledge_search -b '{"inputs": {"text": "Bitcoin price history"}, "output_settings": {"knowledge_card_settings": {"image_dark_mode": true}}}'
```

### Get Chart Insights

```bash
orth run tako /v1/beta/chart_insights -q 'card_id=sXQPVnixcDUf2Iw35Via'
```

### Visualize Your Own Data

Provide data as CSV strings. Tako picks the best chart type automatically.

```bash
orth run tako /v1/beta/visualize -b '{"csv": ["quarter,revenue_millions\nQ1 2024,100\nQ2 2024,150\nQ3 2024,220\nQ4 2024,310"], "query": "Show quarterly revenue as a bar chart"}'
```

Request a specific chart type:

```bash
orth run tako /v1/beta/visualize -b '{"csv": ["region,sales\nUS,500\nEU,300\nAsia,250"], "query": "Sales by region", "viz_component_type": "pie"}'
```

### Create a Custom Chart

Build charts from scratch with full control over components and layout.

```bash
orth run tako /v1/thin_viz/create/ -b '{"components": [{"component_type": "header", "config": {"title": "Sales by Region"}}, {"component_type": "categorical_bar", "config": {"datasets": [{"label": "Revenue (M)", "data": [{"x": "US", "y": 500}, {"x": "EU", "y": 300}, {"x": "Asia", "y": 250}]}]}}], "title": "Sales by Region", "source": "Internal Data"}'
```

### List Available Chart Types

```bash
orth run tako /v1/thin_viz/default_schema/
```

### Get Tako Tool Descriptions

```bash
orth run tako /v1/tako_tools_description
```

## Parameters

### Knowledge Search (POST /v1/knowledge_search)

Body:
- **inputs.text** (string, required) - Natural language query (e.g. "Tesla vs Ford market cap")
- **inputs.search_effort** (string) - "fast", "medium", "deep", or "auto"
- **source_indexes** (array) - Priority order: "tako", "web", "tako_deep_v2". Default: ["tako"]
- **country_code** (string) - ISO 3166-1 alpha-2 (e.g. "US", "GB"). Default: "US"
- **locale** (string) - e.g. "en-US", "de-DE". Default: "en-US"
- **output_settings** (object) - `{"knowledge_card_settings": {"image_dark_mode": true}}` for dark mode

### Chart Insights (GET /v1/beta/chart_insights)

- **card_id** (string, required) - Card ID from Knowledge Search or Create Card response

### Visualize Datasets (POST /v1/beta/visualize)

Body:
- **csv** (array of strings, required) - CSV data with headers in first row. Example: `["name,value\nApple,3.7\nNVIDIA,3.4"]`
- **query** (string) - How to visualize (e.g. "Show as a bar chart")
- **viz_component_type** (string) - Force chart type: bar, grouped_bar, stacked_bar, timeseries, pie, choropleth, scatter, boxplot, heatmap, waterfall, histogram, table, treemap

### Create Card (POST /v1/thin_viz/create/)

Body:
- **components** (array, required) - Each needs `component_type` (header, categorical_bar, pie, scatter, table, choropleth, heatmap, histogram, boxplot, treemap, waterfall, bubble, etc.) and `config` (type-specific data)
- **title** (string) - Card title
- **description** (string) - Card description
- **source** (string) - Data source attribution for footer

### List Default Schemas (GET /v1/thin_viz/default_schema/)

No parameters.

### Tool Descriptions (GET /v1/tako_tools_description)

- **index_ids** (string) - Comma-separated index IDs to filter

## Response

### Knowledge Search — `data.outputs.knowledge_cards[]`

- **card_id** - Unique ID (use for Chart Insights or embed URLs)
- **title** - Chart title
- **description** - Text description of the data and trends
- **card_type** - "chart", "table", "company", or "text"
- **webpage_url** - Interactive card page on Tako
- **image_url** - Static chart image (embed in messages, reports)
- **embed_url** - Embeddable iframe URL
- **relevance** - "High", "Medium", or "Low"
- **sources** - Data sources with name and description
- **visualization_data** - Raw chart data points

### Chart Insights — `data`

- **insights** - Array of AI-generated observations
- **description** - Chart description

### Create Card — `data`

- **card_id**, **title**, **webpage_url**, **image_url**, **embed_url**

## Examples

```bash
# What's the US unemployment rate?
orth run tako /v1/knowledge_search -b '{"inputs": {"text": "US unemployment rate"}}'

# Compare company revenues
orth run tako /v1/knowledge_search -b '{"inputs": {"text": "Apple vs Microsoft vs Google revenue", "search_effort": "deep"}}'

# Get insights on a chart
orth run tako /v1/beta/chart_insights -q 'card_id=sXQPVnixcDUf2Iw35Via'

# Visualize your own CSV data
orth run tako /v1/beta/visualize -b '{"csv": ["region,sales_millions\nNorth America,500\nEurope,300\nAsia,250\nLatAm,100"], "query": "Show sales by region"}'

# Create a custom bar chart
orth run tako /v1/thin_viz/create/ -b '{"components": [{"component_type": "categorical_bar", "config": {"datasets": [{"label": "Revenue", "data": [{"x": "Q1", "y": 100}, {"x": "Q2", "y": 200}]}]}}], "title": "Quarterly Revenue"}'
```

## Tips

- **Knowledge Search** is the main endpoint — start here for any data question
- Use **image_url** to display charts in Slack, Discord, or other channels
- **embed_url** gives an interactive iframe for web pages
- Call **List Default Schemas** before Create Card to see available chart types
- Set `search_effort: "deep"` for complex multi-metric comparisons
- Data coverage: stock prices, revenue, GDP, unemployment, population, sports stats, weather, health, and more

## Error Handling

- **400** - Invalid body or missing required fields
- **401** - Invalid API key
- **404** - Card not found (Chart Insights) or no results found (Knowledge Search)
- Empty `knowledge_cards` array — try rephrasing or using `source_indexes: ["tako", "web"]`