{"id":7998,"library":"cassio","title":"Cassio","description":"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.","status":"active","version":"0.1.10","language":"en","source_language":"en","source_url":"https://github.com/CassioML/cassio","tags":["cassandra","apache-cassandra","datastax","astra-db","llm","genai","ml","vector-database","ai"],"install":[{"cmd":"pip install cassio","lang":"bash","label":"Basic Installation"},{"cmd":"pip install -qU langchain-community \"cassio>=0.1.4\"","lang":"bash","label":"For LangChain Integration"}],"dependencies":[{"reason":"Requires Python 3.9 or higher, but less than 4.0.","package":"python","optional":false},{"reason":"Implicitly required for actual interaction with Apache Cassandra or Astra DB.","package":"cassandra-driver","optional":false}],"imports":[{"note":"The `init` function is typically accessed directly as `cassio.init()` after importing the top-level package.","wrong":"from cassio import init","symbol":"cassio","correct":"import cassio"},{"note":"Used when integrating with LangChain as a vector store.","symbol":"Cassandra","correct":"from langchain_community.vectorstores import Cassandra"},{"note":"Required for creating a direct Cassandra driver session if not using Astra DB with token/database_id.","symbol":"Cluster","correct":"from cassandra.cluster import Cluster"}],"quickstart":{"code":"import os\nimport cassio\n\n# Set these environment variables for Astra DB connection\n# ASTRA_DB_ID = \"your_astra_database_id\"\n# ASTRA_DB_APPLICATION_TOKEN = \"your_astra_application_token\"\n# ASTRA_DB_KEYSPACE = \"your_astra_keyspace\" (optional)\n\n# Initialize Cassio with Astra DB credentials\ntry:\n    cassio.init(\n        database_id=os.environ.get('ASTRA_DB_ID'),\n        token=os.environ.get('ASTRA_DB_APPLICATION_TOKEN'),\n        keyspace=os.environ.get('ASTRA_DB_KEYSPACE', 'default_keyspace')\n    )\n    print(\"Cassio initialized successfully with Astra DB.\")\n\n    # Example: Verify session and keyspace (optional)\n    session = cassio.get_session()\n    keyspace = cassio.get_keyspace()\n    if session and keyspace:\n        print(f\"Connected to keyspace: {keyspace}\")\n    else:\n        print(\"Failed to retrieve session or keyspace after initialization.\")\n\nexcept ValueError as e:\n    print(f\"Cassio initialization failed: {e}\")\n    print(\"Please ensure ASTRA_DB_ID and ASTRA_DB_APPLICATION_TOKEN environment variables are set.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred during Cassio initialization: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or higher (but less than 4.0).","message":"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.","severity":"breaking","affected_versions":">=0.1.10"},{"fix":"Always provide all necessary connection parameters to `cassio.init()` based on your connection method (Astra DB credentials or a `cassandra.cluster.Session` object).","message":"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`.","severity":"breaking","affected_versions":">=0.1.10"},{"fix":"Monitor release notes carefully when upgrading versions and be prepared to adapt your code. Pin exact versions in production environments.","message":"Cassio is currently an alpha release (`0.*` versioning). This implies that occasional breaking changes are still to be expected in minor or patch releases.","severity":"gotcha","affected_versions":"All 0.* versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.1.10"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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()`.","cause":"Attempted to call `cassio.init()` for Astra DB without providing both the database ID and application token, or with `None` values.","error":"ValueError: Invalid arguments for Astra DB connection. Must provide 'database_id' and 'token'."},{"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.","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.","error":"NoHostAvailableError: All host(s) tried for query failed. First host tried, ...: OperationTimedOutError: The host ... did not reply before timeout ... ms."},{"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.","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.","error":"ConnectError: ConnectError: [Errno 111] Connection refused"}]}