RAGStack AI Knowledge Store

Common errors

• ModuleNotFoundError: No module named 'ragstack_ai.knowledge_store'

  cause The `ragstack-ai-knowledge-store` package is not installed or there's a typo in the import path.
  fix Run `pip install ragstack-ai-knowledge-store` to install the package. Double-check the import statement: `from ragstack_ai.knowledge_store import AstraDBKnowledgeStore`.

• astrapy.exceptions.DevOpsAPIException: No database with ID '...' found

  cause The provided `ASTRA_DB_ID` or `ASTRA_DB_APPLICATION_TOKEN` is incorrect or the database does not exist/is not accessible.
  fix Verify your Astra DB ID and Application Token. Ensure they are correctly set as environment variables or passed to the `AstraDBKnowledgeStore` constructor. Check your Astra DB dashboard for the correct ID and ensure the token has sufficient permissions.

• TypeError: add_documents() missing 1 required positional argument: 'documents'

  cause The `add_documents` method expects an iterable (e.g., a list) of `Document` objects, but it received a single `Document` or an incorrect type.
  fix Always pass a list of `Document` objects to `add_documents`, even if it's a list containing only one document: `kg_store.add_documents(documents=[Document(...)])`.

Warnings

• gotcha The PyPI version of `ragstack-ai-knowledge-store` (e.g., 0.2.1) might be significantly lower than the overall `ragstack-ai` project's GitHub release versions (e.g., 1.x.x). This can lead to confusion or dependency conflicts if not managed carefully.
  Fix: Always check the specific PyPI page for `ragstack-ai-knowledge-store` for its correct version and dependencies. Do not assume it is locked to the main `ragstack-ai` project's version.
• breaking This library is tightly coupled with DataStax Astra DB. It does not provide a local or in-memory graph store option. An active Astra DB instance and valid application token/database ID are mandatory for operation.
  Fix: Ensure you have an Astra DB account, a database provisioned, and generate an Application Token. Set `ASTRA_DB_APPLICATION_TOKEN` and `ASTRA_DB_ID` as environment variables or pass them directly to the `AstraDBKnowledgeStore` constructor.
• gotcha While part of the RAGStack ecosystem, `ragstack-ai-knowledge-store` specifically deals with graph data. Its query interface and interaction patterns are different from generic vector stores. Integrating it directly into LangChain or LlamaIndex RAG chains might require specific RAGStack connectors (e.g., `ragstack-ai-langchain`).
  Fix: Familiarize yourself with graph database concepts and the specific methods provided by `AstraDBKnowledgeStore` for adding and retrieving graph-structured data. For full LangChain/LlamaIndex integration, consult the documentation for `ragstack-ai-langchain` or `ragstack-ai-llamaindex`.

Install

• pip install ragstack-ai-knowledge-store Install core package

Imports

• AstraDBKnowledgeStore

  from ragstack_ai.knowledge_store import AstraDBKnowledgeStore

  This is the primary class for interacting with a graph knowledge store in Astra DB.

Quickstart

This quickstart demonstrates how to initialize `AstraDBKnowledgeStore` and add `langchain_core.documents.Document` objects to it. It requires an active Astra DB instance and valid credentials. The `graph_name` parameter identifies your specific knowledge graph within Astra DB.

import os
from ragstack_ai.knowledge_store import AstraDBKnowledgeStore
from langchain_core.documents import Document

# Ensure Astra DB credentials are set as environment variables
# ASTRA_DB_APPLICATION_TOKEN, ASTRA_DB_ID, ASTRA_DB_KEYSPACE (optional, defaults to 'default')

astra_db_token = os.environ.get("ASTRA_DB_APPLICATION_TOKEN", "YOUR_ASTRA_DB_TOKEN")
astra_db_id = os.environ.get("ASTRA_DB_ID", "YOUR_ASTRA_DB_ID")
astra_db_keyspace = os.environ.get("ASTRA_DB_KEYSPACE", "default")

if not all([astra_db_token, astra_db_id]):
    print("Please set ASTRA_DB_APPLICATION_TOKEN and ASTRA_DB_ID environment variables.")
    exit()

try:
    # Initialize the Knowledge Store
    kg_store = AstraDBKnowledgeStore(
        astra_db_id=astra_db_id,
        astra_db_application_token=astra_db_token,
        astra_db_keyspace=astra_db_keyspace,
        graph_name="my_rag_knowledge_graph" # A unique name for your graph
    )

    # Add documents to the knowledge store
    documents = [
        Document(page_content="Leonardo da Vinci was an Italian polymath.", metadata={"source": "wiki"}),
        Document(page_content="The Mona Lisa is a half-length portrait painting by Leonardo da Vinci.", metadata={"source": "wiki"})
    ]

    print("Adding documents...")
    kg_store.add_documents(documents=documents)
    print("Documents added successfully.")

    # Example: Simple graph traversal (conceptual, actual queries depend on graph structure)
    # Note: Complex graph queries typically use specific methods or a dedicated graph query engine.
    # This demonstrates basic interaction.
    print(f"Knowledge Store initialized for graph: {kg_store.graph_name}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure your Astra DB credentials are correct and the database is accessible.")