cassio

library0.1.10pypypi✓ verified 85d ago

Cassio is a framework-agnostic Python library designed for seamless integration of Apache Cassandra® with ML/LLM/genAI workloads. It provides utilities for interacting with Cassandra as a vector store, managing chat memory, and caching LLM responses, often serving as the core engine for higher-level frameworks like LangChain or LlamaIndex. The library is currently in an alpha release (v0.1.10) and has a moderately active release cadence, with occasional breaking changes expected.

database vector-search llm-agents

pip install cassio

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CASSIO

cassio

databasepythonv0.1.10

Install

10.7s avg

Import

1007ms

Disk

250MB

Pass rate

6/ 10

Env Coverage6 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.1.10 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

✓ 11.91s

py 3.11

✕ build_error

✓ 10.63s

py 3.12

✕ build_error

✓ 9.01s

py 3.13

✕ build_error

✓ 9.4s

py 3.9

✓ —

✓ 12.78s

250MB installed

● package 250MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

cassio

✓ import cassio

✗ from cassio import init

The `init` function is typically accessed directly as `cassio.init()` after importing the top-level package.

Cassandra

✓ from langchain_community.vectorstores import Cassandra

Used when integrating with LangChain as a vector store.

Cluster

✓ from cassandra.cluster import Cluster

Required for creating a direct Cassandra driver session if not using Astra DB with token/database_id.

This quickstart demonstrates how to initialize Cassio to connect to DataStax Astra DB using environment variables for the database ID and application token. This is the recommended approach for cloud-based GenAI workloads. It includes error handling for missing credentials during initialization.

import os import cassio # Set these environment variables for Astra DB connection # ASTRA_DB_ID = "your_astra_database_id" # ASTRA_DB_APPLICATION_TOKEN = "your_astra_application_token" # ASTRA_DB_KEYSPACE = "your_astra_keyspace" (optional) # Initialize Cassio with Astra DB credentials try: cassio.init( database_id=os.environ.get('ASTRA_DB_ID'), token=os.environ.get('ASTRA_DB_APPLICATION_TOKEN'), keyspace=os.environ.get('ASTRA_DB_KEYSPACE', 'default_keyspace') ) print("Cassio initialized successfully with Astra DB.") # Example: Verify session and keyspace (optional) session = cassio.get_session() keyspace = cassio.get_keyspace() if session and keyspace: print(f"Connected to keyspace: {keyspace}") else: print("Failed to retrieve session or keyspace after initialization.") except ValueError as e: print(f"Cassio initialization failed: {e}") print("Please ensure ASTRA_DB_ID and ASTRA_DB_APPLICATION_TOKEN environment variables are set.") except Exception as e: print(f"An unexpected error occurred during Cassio initialization: {e}")

Debug

Known issues

breakingAs of v0.1.10, Python 3.8 is no longer supported. Users on Python 3.8 will encounter issues and should upgrade their Python version.

fix

Upgrade your Python environment to 3.9 or higher (but less than 4.0).

affects: >=0.1.10

breakingCalling `cassio.init()` with insufficient arguments (e.g., missing `database_id` or `token` for Astra DB, or `session` for a local Cassandra cluster) now raises a `ValueError`.

fix

Always provide all necessary connection parameters to `cassio.init()` based on your connection method (Astra DB credentials or a `cassandra.cluster.Session` object).

affects: >=0.1.10

gotchaCassio is currently an alpha release (`0.*` versioning). This implies that occasional breaking changes are still to be expected in minor or patch releases.

fix

Monitor release notes carefully when upgrading versions and be prepared to adapt your code. Pin exact versions in production environments.

affects: All 0.* versions

gotchaPrior to v0.1.10, metadata keys containing JSON or curly braces could cause bugs. While fixed, similar issues might arise with complex or malformed metadata if not properly escaped or handled.

fix

Upgrade to v0.1.10 or later. Ensure metadata keys adhere to Cassandra's naming conventions and avoid special characters unless explicitly supported and handled by Cassio.

affects: <0.1.10

Errors

Common errors & fixes

ValueError: Invalid arguments for Astra DB connection. Must provide 'database_id' and 'token'.

Attempted to call `cassio.init()` for Astra DB without providing both the database ID and application token, or with `None` values.

fix

Ensure `ASTRA_DB_ID` and `ASTRA_DB_APPLICATION_TOKEN` environment variables are set correctly, or pass them directly as keyword arguments to `cassio.init()`.

NoHostAvailableError: All host(s) tried for query failed. First host tried, ...: OperationTimedOutError: The host ... did not reply before timeout ... ms.

The Cassandra cluster or Astra DB instance is unreachable, misconfigured, or network issues are preventing the driver from connecting. This can also occur if the wrong `contactPoints` are specified or firewall rules block access.

fix

Verify that your Cassandra cluster or Astra DB instance is running and accessible. Check network connectivity, firewall settings, and ensure the correct `database_id` or contact points are used. If using a direct `cassandra.cluster.Session`, ensure the session is properly initialized and connected.

ConnectError: ConnectError: [Errno 111] Connection refused

This often occurs when trying to connect to a service that is not running or is not listening on the specified port/address. In a `cassio` context, it might arise from an underlying `httpx` error if using a non-direct connection method that relies on HTTP, or if `cassio` cannot establish its initial connection to the database layer.

fix

Double-check the database endpoint and port. Ensure the database service is active and reachable. For Astra DB, verify `database_id` and `token`. If configuring a `session` manually, confirm the `cassandra-driver` connection details are correct.

Upgrade

Version history

0.1.10latest on PyPI · released Oct 3, 2024

Audit

Dependencies

pythonrequiredRequires Python 3.9 or higher, but less than 4.0.

cassandra-driverrequiredImplicitly required for actual interaction with Apache Cassandra or Astra DB.

Agent activity

59 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/CassioML/cassio ↗

packagehttps://pypi.org/project/cassio/ ↗

homepagehttps://cassio.org ↗