Cassio

0.1.10 · active · verified Thu Apr 16

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.

Common errors

```
ValueError: Invalid arguments for Astra DB connection. Must provide 'database_id' and 'token'.
```
cause 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.
```
cause 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
```
cause 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.

Warnings

breaking As 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).
breaking Calling `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).
gotcha Cassio 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.
gotcha Prior 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.

Install

pip install cassio Basic Installation
pip install -qU langchain-community "cassio>=0.1.4" For LangChain Integration

Imports

cassio
wrong:
```
from cassio import init
```
correct:
```
import cassio
```
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.

Quickstart

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}")

view raw JSON →