data-charts-tako

# Tako Knowledge Search & Visualization

## Setup

Read your credentials from ~/.gooseworks/credentials.json:
```bash
export GOOSEWORKS_API_KEY=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json'))['api_key'])")
export GOOSEWORKS_API_BASE=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json')).get('api_base','https://api.gooseworks.ai'))")
```

If ~/.gooseworks/credentials.json does not exist, tell the user to run: `npx gooseworks login`

All endpoints use Bearer auth: `-H "Authorization: Bearer $GOOSEWORKS_API_KEY"`


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
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"tako","path":"/v1/knowledge_search","body":{"inputs":{"text":"NVIDIA vs AMD revenue since 2018"}}}'
```

With search effort and source options:

```bash
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"tako","path":"/v1/knowledge_search","body":{"inputs":{"text":"US inflation rate 2020-2025","search_effort":"deep"},"source_indexes":["tako","web"]}}'
```

With dark mode chart images:

```bash
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"tako","path":"/v1/knowledge_search","body":{"inputs":{"text":"Bitcoin price history"},"output_settings":{"knowledge_card_settings":{"image_dark_mode":true}}}}'
```

### Get Chart Insights

```bash
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"tako","path":"/v1/beta/chart_insights","query":{"card_id":"sXQPVnixcDUf2Iw35Via"}}'
```

### Visualize Your Own Data

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

```bash
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"tako","path":"/v1/beta/visualize"}'
Q1 2024,100
Q2 2024,150
Q3 2024,220
Q4 2024,310"], "query": "Show quarterly revenue as a bar chart"}'
```

Request a specific chart type:

```bash
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"tako","path":"/v1/beta/visualize"}'
US,500
EU,300
Asia,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
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"tako","path":"/v1/thin_viz/create/","body":{"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
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"tako","path":"/v1/thin_viz/default_schema/"}'
```

### Get Tako Tool Descriptions

```bash
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"tako","path":"/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
Apple,3.7
NVIDIA,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_schem