LangChain Integration¶

langchain-akasicdb is the AkasicDB integration package for LangChain. It provides a LangChain VectorStore implementation backed by AkasicDB and a graph wrapper for executing Cypher queries against AkasicDB graphs.

Requirements¶

Python 3.11 or later
A running AkasicDB instance
The AkasicDB extension enabled in the target database
An embedding model that implements LangChain's Embeddings interface

Start AkasicDB first by following the Quick Start guide.

Installation¶

Install the LangChain integration package.

pip install "langchain-akasicdb"

The package depends on akasicdb[sdk], langchain-core, psycopg, and numpy.

Import Paths¶

Use the langchain_akasicdb package.

from langchain_akasicdb import AkasicDBVector, AkasicDBGraph

Connection URLs¶

AkasicDBVector uses a SQLAlchemy-style PostgreSQL URL because it uses the AkasicDB Python SDK underneath.

postgresql+psycopg://postgres:mysecretpassword@localhost:5432/postgres

AkasicDBGraph uses a Psycopg-style PostgreSQL URL because it executes graph queries directly through Psycopg.

postgresql://postgres:mysecretpassword@localhost:5432/postgres

Vector Store¶

AkasicDBVector implements LangChain's VectorStore interface. It stores document text, metadata, and embeddings in an AkasicDB collection.

from langchain_akasicdb import AkasicDBVector

vector_store = AkasicDBVector(
    embedding=embeddings,
    dimension=1536,
    db_url="postgresql+psycopg://postgres:mysecretpassword@localhost:5432/postgres",
    collection_name="docs",
    new_table=True,
)

Constructor arguments:

Argument	Description
`embedding`	LangChain `Embeddings` implementation
`dimension`	Embedding vector dimension
`db_url`	SQLAlchemy-style AkasicDB connection URL
`collection_name`	AkasicDB collection name. Defaults to `langchain`
`new_table`	Recreate the collection table when `True`

Create from Texts or Documents¶

Use from_texts() or from_documents() when you want to create a collection and add content in one step. The embedding dimension is automatically detected from embedding.

from langchain_core.documents import Document
from langchain_akasicdb import AkasicDBVector

docs = [
    Document(page_content="AkasicDB supports vector search.", metadata={"source": "manual"}),
    Document(page_content="LangChain can use AkasicDB as a VectorStore.", metadata={"source": "manual"}),
]

vector_store = AkasicDBVector.from_documents(
    documents=docs,
    embedding=embeddings,
    db_url="postgresql+psycopg://postgres:mysecretpassword@localhost:5432/postgres",
    collection_name="docs",
)

Add and Delete Documents¶

Use LangChain's standard add_texts(), add_documents(), and delete() methods.

ids = vector_store.add_texts(
    ["hello akasicdb", "hello langchain"],
    metadatas=[{"topic": "db"}, {"topic": "llm"}],
)

vector_store.delete(ids=[ids[0]])

Similarity Search¶

Use similarity_search() for documents only, or similarity_search_with_score() when you need scores.

docs = vector_store.similarity_search(
    "How do I store embeddings?",
    k=3,
    filter={"topic": "db"},
)

docs_with_scores = vector_store.similarity_search_with_score(
    "How do I store embeddings?",
    k=3,
)

Supported distance_func values:

Value	AkasicDB operator	Meaning
`sqrt_euclid`	`<->`	L2 distance
`neg_dot_prod`	`<#>`	Negative dot product
`ned_cos`	`<=>`	Cosine distance

docs = vector_store.similarity_search(
    "graph vector search",
    k=5,
    distance_func="ned_cos",
)

Maximal Marginal Relevance¶

Use MMR search when you want results that balance similarity and diversity.

docs = vector_store.max_marginal_relevance_search(
    "graph vector search",
    k=4,
    fetch_k=20,
    lambda_mult=0.5,
)

MMR supports sqrt_euclid and ned_cos distance functions.

Retrieval¶

AkasicDBVector can be used as a LangChain retriever through as_retriever().

retriever = vector_store.as_retriever(
    search_type="similarity",
    search_kwargs={"k": 4},
)

docs = retriever.invoke("What is AkasicDB?")

Graph Wrapper¶

AkasicDBGraph provides a LangChain-compatible graph wrapper for AkasicDB graph queries. The graph must already be defined and created in AkasicDB.

from langchain_akasicdb import AkasicDBGraph

graph = AkasicDBGraph(
    db_url="postgresql://postgres:mysecretpassword@localhost:5432/postgres",
    graph_name="retail_graph",
)

rows = graph.query("""
MATCH (c:v_customer)-[:buy]->(i:v_item)
RETURN c.first_name AS customer, i.name AS item
""")

Constructor arguments:

Argument	Description
`db_url`	Psycopg-style AkasicDB connection URL
`graph_name`	Name of the AkasicDB graph
`refresh_schema`	Load schema metadata on initialization. Defaults to `True`

Query Parameters¶

Pass parameters using params. Reference them in the query like $name.

rows = graph.query(
    """
    MATCH (c:v_customer)
    WHERE c.first_name = $name
    RETURN c.last_name AS last_name
    """,
    params={"name": "Margaret"},
)

Schema Introspection¶

AkasicDBGraph exposes schema information in a human-readable string and a structured dictionary.

print(graph.get_schema)
schema = graph.get_structured_schema

Use refresh_schema() after recreating or changing the graph definition.

graph.refresh_schema()

Compatibility Notes¶

AkasicDBVector.get_by_ids() is not implemented in the current package.
The vector store creates AkasicDB collection tables through the AkasicDB Python SDK.
The graph wrapper executes Cypher against an existing AkasicDB graph; it does not create graph definitions.