Catsu Logo

🐱 catsu

A unified, batteries-included client for embedding APIs that actually works.

The world of embedding API clients is broken.

Everyone defaults to OpenAI's client for embeddings, even though it wasn't designed for that purpose
Provider-specific libraries (VoyageAI, Cohere, etc.) are inconsistent, poorly maintained, or outright broken
Universal clients like LiteLLM don't focus on embeddings—they rely on native client libraries, inheriting all their problems
Every provider has different capabilities—some support dimension changes, others don't—with no standardized way to discover what's available
Most clients lack basic features like retry logic, proper error handling, and usage tracking

Catsu fixes this. It's a high-performance, unified client built specifically for embeddings with:

🎯 A clean, consistent API across all providers
🔄 Built-in retry logic with exponential backoff
💰 Automatic usage and cost tracking
📚 Rich model metadata and capability discovery
⚡ Rust core with Python bindings for maximum performance

Installation

pip install catsu

Quick Start

from catsu import Client

# Create client (reads API keys from environment)
client = Client()

# Generate embeddings
response = client.embed(
    "openai:text-embedding-3-small",
    ["Hello, world!", "How are you?"]
)

print(f"Dimensions: {response.dimensions}")
print(f"Tokens used: {response.usage.tokens}")
print(f"Embedding: {response.embeddings[0][:5]}")

Async Support

import asyncio
from catsu import Client

async def main():
    client = Client()
    response = await client.aembed(
        "openai:text-embedding-3-small",
        "Hello, async world!"
    )
    print(response.embeddings[0][:5])

asyncio.run(main())

With Options

response = client.embed(
    "openai:text-embedding-3-small",
    ["Search query"],
    input_type="query",  # "query" or "document"
    dimensions=256,      # output dimensions (if supported)
)

Model Catalog

# List all available models
models = client.list_models()

# Filter by provider
openai_models = client.list_models("openai")
for m in openai_models:
    print(f"{m.name}: {m.dimensions} dims, ${m.cost_per_million_tokens}/M tokens")

Configuration

client = Client(
    max_retries=5,   # Default: 3
    timeout=60,      # Default: 30 seconds
)

NumPy Integration

# Convert embeddings to numpy array
arr = response.to_numpy()
print(arr.shape)  # (2, 1536)

Context Manager

# Sync
with Client() as client:
    response = client.embed("openai:text-embedding-3-small", "Hello!")

# Async
async with Client() as client:
    response = await client.aembed("openai:text-embedding-3-small", "Hello!")

If you found this helpful, consider giving it a ⭐!

made with ❤️ by chonkie, inc.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

catsu-0.1.8.tar.gz (50.0 kB view details)

Uploaded Feb 20, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

catsu-0.1.8-cp313-cp313-win_amd64.whl (2.0 MB view details)

Uploaded Feb 20, 2026 CPython 3.13Windows x86-64

catsu-0.1.8-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.4 MB view details)

Uploaded Feb 20, 2026 CPython 3.13manylinux: glibc 2.17+ x86-64

catsu-0.1.8-cp313-cp313-macosx_11_0_arm64.whl (2.1 MB view details)

Uploaded Feb 20, 2026 CPython 3.13macOS 11.0+ ARM64

catsu-0.1.8-cp313-cp313-macosx_10_12_x86_64.whl (2.2 MB view details)

Uploaded Feb 20, 2026 CPython 3.13macOS 10.12+ x86-64

catsu-0.1.8-cp312-cp312-win_amd64.whl (2.0 MB view details)

Uploaded Feb 20, 2026 CPython 3.12Windows x86-64

catsu-0.1.8-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.4 MB view details)

Uploaded Feb 20, 2026 CPython 3.12manylinux: glibc 2.17+ x86-64

catsu-0.1.8-cp312-cp312-macosx_11_0_arm64.whl (2.1 MB view details)

Uploaded Feb 20, 2026 CPython 3.12macOS 11.0+ ARM64

catsu-0.1.8-cp312-cp312-macosx_10_12_x86_64.whl (2.2 MB view details)

Uploaded Feb 20, 2026 CPython 3.12macOS 10.12+ x86-64

catsu-0.1.8-cp311-cp311-win_amd64.whl (2.0 MB view details)

Uploaded Feb 20, 2026 CPython 3.11Windows x86-64

catsu-0.1.8-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.4 MB view details)

Uploaded Feb 20, 2026 CPython 3.11manylinux: glibc 2.17+ x86-64

catsu-0.1.8-cp311-cp311-macosx_11_0_arm64.whl (2.2 MB view details)

Uploaded Feb 20, 2026 CPython 3.11macOS 11.0+ ARM64

catsu-0.1.8-cp311-cp311-macosx_10_12_x86_64.whl (2.2 MB view details)

Uploaded Feb 20, 2026 CPython 3.11macOS 10.12+ x86-64

catsu-0.1.8-cp310-cp310-win_amd64.whl (2.0 MB view details)

Uploaded Feb 20, 2026 CPython 3.10Windows x86-64

catsu-0.1.8-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.4 MB view details)

Uploaded Feb 20, 2026 CPython 3.10manylinux: glibc 2.17+ x86-64

catsu-0.1.8-cp310-cp310-macosx_11_0_arm64.whl (2.2 MB view details)

Uploaded Feb 20, 2026 CPython 3.10macOS 11.0+ ARM64

catsu-0.1.8-cp310-cp310-macosx_10_12_x86_64.whl (2.2 MB view details)

Uploaded Feb 20, 2026 CPython 3.10macOS 10.12+ x86-64

File details

Details for the file catsu-0.1.8.tar.gz.

File metadata

Download URL: catsu-0.1.8.tar.gz
Upload date: Feb 20, 2026
Size: 50.0 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8.tar.gz
Algorithm	Hash digest
SHA256	`961cbc239e77b32ee08e5498a7ddcb83a3c08b025fb3fc504f97c14569e9aa74`
MD5	`38bec7982aec6bb619b093c9d718db3a`
BLAKE2b-256	`855484b62d54afe2695a9170f6f434dc8912976a57bf6680aa99557eadb3676f`

See more details on using hashes here.

File details

Details for the file catsu-0.1.8-cp313-cp313-win_amd64.whl.

File metadata

Download URL: catsu-0.1.8-cp313-cp313-win_amd64.whl
Upload date: Feb 20, 2026
Size: 2.0 MB
Tags: CPython 3.13, Windows x86-64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8-cp313-cp313-win_amd64.whl
Algorithm	Hash digest
SHA256	`50ff392f5b9f0ad18fc11496f62079e36bb57270b5bca966feda220744139fa5`
MD5	`1472c2df7a4b4d5be3d73e0386da3917`
BLAKE2b-256	`4bce254323b237e230e5534b3226551172357751c9633438327a939104b56551`

See more details on using hashes here.

File details

Details for the file catsu-0.1.8-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: catsu-0.1.8-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Feb 20, 2026
Size: 2.4 MB
Tags: CPython 3.13, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`97b84a6412562370ac42270c965ea065d4f8a8f66eb706ac8d4ab5544fbe38fd`
MD5	`6a98a8a642c42311df66c33f6a9ba8ea`
BLAKE2b-256	`7672edb51405083f3c9e87c0c30498b5ade0950eec8968d986c0baf1723ebb02`

See more details on using hashes here.

File details

Details for the file catsu-0.1.8-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

Download URL: catsu-0.1.8-cp313-cp313-macosx_11_0_arm64.whl
Upload date: Feb 20, 2026
Size: 2.1 MB
Tags: CPython 3.13, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8-cp313-cp313-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`e1a81d2098e5dfb1e2394c7eeb594fe349451ebe4b51994e54dde5e4f06ecdb9`
MD5	`73d68191495adad6d136b76da650d4a2`
BLAKE2b-256	`bad55f8e90bfcd5b5c3b9e9e51fa644856fa89fb5f4e1f2cefd9e87be05d2e2d`

See more details on using hashes here.

File details

Details for the file catsu-0.1.8-cp313-cp313-macosx_10_12_x86_64.whl.

File metadata

Download URL: catsu-0.1.8-cp313-cp313-macosx_10_12_x86_64.whl
Upload date: Feb 20, 2026
Size: 2.2 MB
Tags: CPython 3.13, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8-cp313-cp313-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`6805074bbfb0c9df144834a02af14573ab423d822207d735b297fb5bed74dee4`
MD5	`17493785f4e450df9dc98eb3f0466ae3`
BLAKE2b-256	`5ba43542483167e1a98998a2d5fb39a50978200c703d8f5fc9ac63acb529ee29`

See more details on using hashes here.

File details

Details for the file catsu-0.1.8-cp312-cp312-win_amd64.whl.

File metadata

Download URL: catsu-0.1.8-cp312-cp312-win_amd64.whl
Upload date: Feb 20, 2026
Size: 2.0 MB
Tags: CPython 3.12, Windows x86-64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8-cp312-cp312-win_amd64.whl
Algorithm	Hash digest
SHA256	`87f179efa920f10b7d3f8ef4c54d18c53f827d9ee2fc3b4e919b4c1a005d2758`
MD5	`876877b90cde8129de0546b07dd7ae9a`
BLAKE2b-256	`8feb3376890cf51b4bdd283db654d6d3b2fb98d6d26cc97c2a8af2097be1eb65`

See more details on using hashes here.

File details

Details for the file catsu-0.1.8-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: catsu-0.1.8-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Feb 20, 2026
Size: 2.4 MB
Tags: CPython 3.12, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`2629b7a0827574426761575fe549754628d023db7be3b9450a6c05f91e6d249f`
MD5	`36a6307396f21313d95504cdfdc06d1d`
BLAKE2b-256	`bbbdbfc3d49cb8ca68e08521eea0fd61c120e80f8d52b25beeed39d058e383cd`

See more details on using hashes here.

File details

Details for the file catsu-0.1.8-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

Download URL: catsu-0.1.8-cp312-cp312-macosx_11_0_arm64.whl
Upload date: Feb 20, 2026
Size: 2.1 MB
Tags: CPython 3.12, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8-cp312-cp312-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`7a27211d2b0a8bc449c7bf8f553c3add438bf9a2e48cc7a5176e39c103fe8369`
MD5	`bf5fd720d4b2c6e5c9d905fa86fbc5f6`
BLAKE2b-256	`f5dd057b3a4591d65fc42605ed6a955dd68797dcc8aea0e02f4ca5990e5edc86`

See more details on using hashes here.

File details

Details for the file catsu-0.1.8-cp312-cp312-macosx_10_12_x86_64.whl.

File metadata

Download URL: catsu-0.1.8-cp312-cp312-macosx_10_12_x86_64.whl
Upload date: Feb 20, 2026
Size: 2.2 MB
Tags: CPython 3.12, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8-cp312-cp312-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`4fa79883486405b81a1eb79081505a69c3c0f4a782b7199724fc2c15eb6b0274`
MD5	`b96c3496b499691972b1a81905c9955f`
BLAKE2b-256	`78e8e337d7d95f58bb950e0dd5a969b36b7188fa79e4c4341a3da9e36e3ea1ea`

See more details on using hashes here.

File details

Details for the file catsu-0.1.8-cp311-cp311-win_amd64.whl.

File metadata

Download URL: catsu-0.1.8-cp311-cp311-win_amd64.whl
Upload date: Feb 20, 2026
Size: 2.0 MB
Tags: CPython 3.11, Windows x86-64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8-cp311-cp311-win_amd64.whl
Algorithm	Hash digest
SHA256	`f361bed7fd96ccca79cf32d0954da65cb8ea2e40cf1debc25cfb7b1974aa4d9f`
MD5	`d4200b9d32f69c7be23679530049d875`
BLAKE2b-256	`560c24530d03d26294007a6bd24d0471820aef2b511cab2ba1148c00b007d023`

See more details on using hashes here.

File details

Details for the file catsu-0.1.8-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: catsu-0.1.8-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Feb 20, 2026
Size: 2.4 MB
Tags: CPython 3.11, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`662ca297cd6c0a3b192bca49db9849ae72d8c91b44c9c02333f96889375a038a`
MD5	`1ec940093e783f299951f022a7b8145d`
BLAKE2b-256	`24ad9b2fca366f11f8fe26105ff923b3e44f4f8e7b2cb31cbaa0540a0dd6f331`

See more details on using hashes here.

File details

Details for the file catsu-0.1.8-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

Download URL: catsu-0.1.8-cp311-cp311-macosx_11_0_arm64.whl
Upload date: Feb 20, 2026
Size: 2.2 MB
Tags: CPython 3.11, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8-cp311-cp311-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`037e67c4356686bcaed278dcc3628b00155af26d22b136937890df1834c3a96d`
MD5	`0770071a1b847d1cade6eca57611d8b2`
BLAKE2b-256	`b1599a79127ec5be65dcd94dc2a45e01514c78a517879fdec93de465d6a22bd1`

See more details on using hashes here.

File details

Details for the file catsu-0.1.8-cp311-cp311-macosx_10_12_x86_64.whl.

File metadata

Download URL: catsu-0.1.8-cp311-cp311-macosx_10_12_x86_64.whl
Upload date: Feb 20, 2026
Size: 2.2 MB
Tags: CPython 3.11, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8-cp311-cp311-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`01b7c7091ad2f50d478c0ee92f3823f6593310bc444853f3b1096955f0595542`
MD5	`71dfd6ab9791305da9e1c54397cd3534`
BLAKE2b-256	`c50395c1b55e35ccaeeb71e85bf0f1387fa8a934c22de00a7c206b2227d370e7`

See more details on using hashes here.

File details

Details for the file catsu-0.1.8-cp310-cp310-win_amd64.whl.

File metadata

Download URL: catsu-0.1.8-cp310-cp310-win_amd64.whl
Upload date: Feb 20, 2026
Size: 2.0 MB
Tags: CPython 3.10, Windows x86-64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8-cp310-cp310-win_amd64.whl
Algorithm	Hash digest
SHA256	`e9056b30518b1ec7406198a84ef6e38b3ee094a5876fcd0167147edee82b2970`
MD5	`0affba0ded3a64118dc6831afe865ce3`
BLAKE2b-256	`f427e5cabfdfebdd23faf28a7b64c9deae204680e9df4bdd587155579e872178`

See more details on using hashes here.

File details

Details for the file catsu-0.1.8-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: catsu-0.1.8-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Feb 20, 2026
Size: 2.4 MB
Tags: CPython 3.10, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`099e029352e4d593813cfd634b35b190d09447e2e3ea50034af9913592c73a53`
MD5	`d63ace87645cffed22bbbcf82982a4bc`
BLAKE2b-256	`f3d541883a746e63a37726401b42e4119fe82745df453bbf51a7aa36654a221f`

See more details on using hashes here.

File details

Details for the file catsu-0.1.8-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

Download URL: catsu-0.1.8-cp310-cp310-macosx_11_0_arm64.whl
Upload date: Feb 20, 2026
Size: 2.2 MB
Tags: CPython 3.10, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8-cp310-cp310-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`c80d2bb4e83235ac3979a8d1e49384f06fea63ed800269729023ffd6484711c2`
MD5	`fee53c3aa603d9c80f00bd42a181e375`
BLAKE2b-256	`47eee203be16bc147adc8ef32430bbbbdae277c16baf72142593c17b51d16348`

See more details on using hashes here.

File details

Details for the file catsu-0.1.8-cp310-cp310-macosx_10_12_x86_64.whl.

File metadata

Download URL: catsu-0.1.8-cp310-cp310-macosx_10_12_x86_64.whl
Upload date: Feb 20, 2026
Size: 2.2 MB
Tags: CPython 3.10, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for catsu-0.1.8-cp310-cp310-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`e3a7f06ea7881733595df48dfe33f03b8e0c560d66c1846ddbb28ccc4d49b220`
MD5	`2995f0199a1d09b13db274c2d6215825`
BLAKE2b-256	`9635d4ba15f62b6c8d6ad06d36b865a2bb7149e6932ca6d80ae7a5647693c60e`

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

0.1.8 This release

Feb 20, 2026 17 files

0.1.7

Jan 16, 2026 17 files

0.1.6

Jan 12, 2026 17 files

Jan 7, 2026 17 files

Jan 7, 2026 17 files

Dec 14, 2025 2 files

Dec 11, 2025 2 files

Pre-release

0.0.1a2

Dec 10, 2025 2 files

Pre-release

0.0.1a1

Dec 9, 2025 2 files

Pre-release

0.0.1a0

Dec 9, 2025 2 files

catsu 0.1.8

🐱 catsu

Installation

Quick Start

Async Support

With Options

Model Catalog

Configuration

NumPy Integration

Context Manager

Project links

Key dates

1 maintainer

Credits

License

Requires

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

Release history Release notifications | RSS feed