Tinker API

A REST API backend for fine-tuning LLMs using the Tinker platform. Built with Robyn (high-performance Python web framework with Rust runtime).

Features

• Model Management - List available base models from Tinker
• Dataset Upload - Upload JSONL training datasets or import from HuggingFace Hub
• HuggingFace Integration - Auto-detect Q&A columns, preview, and import datasets
• Training Jobs - Create, monitor, and cancel LoRA fine-tuning jobs
• Inference - Sample from fine-tuned models
• Async Worker - Background job processing with SQLite persistence

Requirements

• Python 3.13+
• uv package manager
• Tinker API key

Quick Start

# Install dependencies
uv sync

# Configure environment
cp .env.example .env
# Edit .env and add your TINKER_API_KEY

# Start API server
uv run python -m app.api.main

# Start worker (in another terminal)
uv run python -m app.worker.main

API available at http://127.0.0.1:8080 | Docs at http://127.0.0.1:8080/docs

Configuration

# Required
TINKER_API_KEY=your-tinker-api-key

# Optional
HF_API_KEY=your-huggingface-token    # For private HF datasets
API_KEY=                              # API auth (empty = disabled)
PORT=8080
DB_PATH=/tmp/tinker_jobs.db
DATA_DIR=/tmp/tinker_data

API Reference

Core Endpoints

Method	Endpoint	Description
GET	/health	Health check
GET	/v1/models	List available models
POST	/v1/datasets	Upload JSONL dataset
POST	/v1/jobs	Create training job
GET	/v1/jobs/:id	Get job status
POST	/v1/jobs/:id/cancel	Cancel job
POST	/v1/sampling	Sample from model
POST	/v1/logprobs	Compute logprobs

HuggingFace Endpoints

Method	Endpoint	Description
GET	/v1/hf/datasets/popular	List popular Q&A datasets
POST	/v1/hf/datasets/preview	Preview dataset before import
POST	/v1/hf/datasets/import	Import dataset to JSONL
POST	/v1/hf/datasets/import-and-train	Import + create job (one-step)

Usage Examples

Upload Dataset & Train

# 1. Upload JSONL dataset
curl -X POST -H 'Content-Type: application/octet-stream' \
  --data-binary @dataset.jsonl \
  http://127.0.0.1:8080/v1/datasets

# 2. Create training job
curl -X POST -H 'Content-Type: application/json' \
  -d '{
    "base_model": "meta-llama/Llama-3.2-1B",
    "dataset_id": "your-dataset-id",
    "steps": 100,
    "batch_size": 4
  }' \
  http://127.0.0.1:8080/v1/jobs

# 3. Check job status
curl http://127.0.0.1:8080/v1/jobs/your-job-id

Import from HuggingFace & Train (One-Step)

curl -X POST -H 'Content-Type: application/json' \
  -d '{
    "dataset_name": "databricks/databricks-dolly-15k",
    "base_model": "meta-llama/Llama-3.2-1B",
    "max_examples": 500,
    "steps": 200
  }' \
  http://127.0.0.1:8080/v1/hf/datasets/import-and-train

Sample from Trained Model

# Use sampler_path from job status (not final_checkpoint_path)
curl -X POST -H 'Content-Type: application/json' \
  -d '{
    "model_path": "tinker://session/sampler_weights/job-sampler",
    "prompt": "What is machine learning?",
    "max_tokens": 100,
    "temperature": 0.7
  }' \
  http://127.0.0.1:8080/v1/sampling

Dataset Format

JSONL Format

{"input": "What is Python?", "output": "Python is a programming language."}
{"input": "Explain APIs", "output": "APIs allow software to communicate."}

Auto-Detected HuggingFace Formats

Format	Input Column	Output Column
Q&A	question	answer
Instruction	instruction	output / response
Chat	prompt	completion / response
SQuAD-style	context + question	answers

Popular Datasets

Dataset	Description
rajpurkar/squad	Context-based Q&A
databricks/databricks-dolly-15k	Instruction following
tatsu-lab/alpaca	Instruction tuning
HuggingFaceH4/no_robots	High-quality instructions
gsm8k	Math word problems

Docker

# Set environment variables in .env, then:
docker-compose up

Testing

./test_backend.sh

# With API authentication
API_KEY="your-key" ./test_backend.sh

Project Structure

tinker-api/
├── app/
│   ├── api/
│   │   ├── main.py           # API server
│   │   ├── db.py             # Database utilities
│   │   ├── hf_datasets.py    # HuggingFace integration
│   │   └── routes/           # API endpoints
│   └── worker/
│       ├── main.py           # Worker process
│       └── tinker_runner.py  # Tinker SDK integration
├── sql/                      # Database schema
├── .env.example              # Config template
├── docker-compose.yml
├── test_backend.sh
└── pyproject.toml

Training Tips

• More data: 100+ examples for meaningful results
• More steps: 100-1000+ steps depending on dataset size
• Monitor loss: Should decrease over training
• Use checkpoints: Set checkpoint_every to save progress

Available Models

Common options (check /v1/models for full list):

• meta-llama/Llama-3.2-1B - Fast, good for testing
• meta-llama/Llama-3.1-8B - Balanced performance
• Qwen/Qwen3-8B - Strong multilingual
• deepseek-ai/DeepSeek-V3.1 - Large model

License

MIT