Metadata-Version: 2.4
Name: langchain-volcengine-mysql
Version: 0.1.0
Summary: langchain intergration for Volcengine veDB for MySQL and RDS for MySQL
Project-URL: Homepage, https://github.com/volcengine/langchain-volcengine-mysql
Project-URL: Repository, https://github.com/volcengine/langchain-volcengine-mysql
Author-email: Siyu Chen <chen.siyu@bytedance.com>
License: Apache-2.0
License-File: LICENSE
Keywords: chat-history,langchain,mysql,rds,vectorstore,vedb
Requires-Python: >=3.8
Requires-Dist: langchain>=0.2.0
Requires-Dist: pymysql>=1.1.0
Requires-Dist: typing-extensions>=4.9.0
Description-Content-Type: text/markdown

English | [中文README](README.zh_CN.md)

# LangChain – Volcengine MySQL Ecosystem

A unified, lightweight adapter package for LangChain users who work with MySQL in Volcengine environments. It provides one import surface for two powerful, externally-available database backends:

- **veDB for MySQL**: A cloud-native, high-performance database service from Volcengine.
- **RDS for MySQL**: A fully managed, stable, and scalable relational database service.

Both adapters are bundled in this package, offering a consistent, attribute-style API for creating and using vector stores and retrievers.

## Overview

Official docs: [veDB for MySQL](https://www.volcengine.com/docs/6357) · [RDS for MySQL](https://www.volcengine.com/docs/6313)

This package simplifies using veDB for MySQL and RDS for MySQL as vector stores in LangChain applications. It abstracts the backend-specific details and provides a clean, unified interface.

- **For veDB for MySQL**: It leverages the `vedbsearch` client library for efficient vector search.
- **For RDS for MySQL**: It utilizes the native vector indexing and search capabilities available in recent versions.

## Features

- **Unified API**: A single package to interact with both veDB for MySQL and RDS for MySQL.
- **Attribute-style Access**: Use `vedb.vector_store` and `mysql.vector_store` to get configured vector store instances.
- **Easy Configuration**: Configure database connections and embedding functions with `configure()` and `set_embedding()`.


- **Standard LangChain Integration**: Fully compatible with the LangChain ecosystem, including chains and other components.

## Installation

Install the unified SDK:

```bash
pip install langchain-volcengine-mysql
```

This single installation includes all necessary components to connect to both veDB for MySQL and RDS for MySQL.

## Import Style & Backend Selection

Select the backend by importing the corresponding submodule and configuring defaults.

```python
# veDB for MySQL
from langchain_volcengine_mysql import vedb
vedb.configure(host="...", user="...", password="...", database="...", table_name="...", embedding_function=embeddings)
vector_store = vedb.vector_store
retriever = vedb.retriever

# RDS for MySQL
from langchain_volcengine_mysql import mysql
mysql.configure(host="...", user="...", password="...", database="...", table_name="...", embedding_function=embeddings)
vector_store = mysql.vector_store
retriever = mysql.retriever
```

## Quickstart

Choose a backend by importing the corresponding submodule. Then, configure it and access the `vector_store` or `retriever` attributes.

### Vector Store (veDB for MySQL)

```python
from langchain_core.embeddings import FakeEmbeddings
from langchain_volcengine_mysql import vedb

# 1. Configure the connection and embedding function
embeddings = FakeEmbeddings(size=768)
vedb.configure(
    host="your-vedb-host.example.com",
    port=3306,
    user="your_user",
    password="your_password",
    database="your_db",
    table_name="vector_embeddings",
    embedding_dim=768,
    embedding_function=embeddings,
)

# 2. Access the vector store and retriever
vector_store = vedb.vector_store
retriever = vedb.retriever

# 3. Add texts and perform searches
vector_store.add_texts(
    [
        "veDB for MySQL is a cloud-native database in Volcengine.",
        "LangChain is a framework for building LLM applications.",
    ],
    metadatas=[{"source": "doc1"}, {"source": "doc2"}],
)

# Similarity search via vector store
results = vector_store.similarity_search("What is veDB?", k=1)
print(results)

# Retriever usage: fetch relevant documents
docs = retriever.get_relevant_documents("What is veDB?")
print([d.page_content for d in docs])
```

### Vector Store (RDS for MySQL)

```python
from langchain_core.embeddings import FakeEmbeddings
from langchain_volcengine_mysql import mysql

# 1. Configure the connection and embedding function
embeddings = FakeEmbeddings(size=1024)
mysql.configure(
    host="your-mysql-host.example.com",
    port=3306,
    user="your_user",
    password="your_password",
    database="your_db",
    table_name="langchain_vectors",
    embedding_function=embeddings,
)

# 2. Access the vector store and retriever
vector_store = mysql.vector_store
retriever = mysql.retriever

# 3. Add texts and perform searches
vector_store.add_texts(
    ["Example sentence one.", "Example sentence two."],
    metadatas=[{"source": "demo1"}, {"source": "demo2"}],
)

# Similarity search via vector store
print(vector_store.similarity_search("Example", k=2))

# Retriever usage: fetch relevant documents
docs = retriever.get_relevant_documents("Example")
print([d.page_content for d in docs])
```

## Configuration

Configuration is handled at the module level using the `configure()` function.

### Configuration Parameters

| Parameter | Type | Description | veDB | RDS |
| --- | --- | --- | :---: | :---: |
| `host` | `str` | Database host. | ✅ | ✅ |
| `port` | `int` | Database port. | ✅ | ✅ |
| `user` | `str` | Database user. | ✅ | ✅ |
| `password` | `str` | Database password. | ✅ | ✅ |
| `database` | `str` | Database name. | ✅ | ✅ |
| `table_name` | `str` | Table for storing vectors. | ✅ | ✅ |
| `embedding_function` | `Embeddings` | LangChain embeddings model. | ✅ | ✅ |
| `embedding_dim` | `int` | Dimension of the vectors. | ✅ | ❌ |
| `index_name` | `str` | Name of the vector index. | ❌ | ✅ |
| `distance` | `MySQLVectorDistance` or `str` | Distance metric for search. | ❌ | ✅ |

### Environment Variables

As an alternative to `configure()`, you can set environment variables for the connection parameters. The `embedding_function` must still be set using `set_embedding()`.

## Getting a Volcano Engine Account & veDB/RDS for MySQL (Quick Guide)

- Sign up or log in to the Volcano Engine Console.
- Enable the veDB for MySQL or RDS for MySQL service.
- Create a MySQL-compatible instance.
- Note your connection info: host, port, database, user, password.
- Configure IP allowlist and TLS if required.
- Map these values into the SDK via `vedb.configure(...)` / `mysql.configure(...)`.

```python
# veDB for MySQL
from langchain_volcengine_mysql import vedb
vedb.configure(
    host="vedb-host.example.com",
    port=3306,
    user="admin",
    password="***",
    database="app_db",
    table_name="vectors",
    embedding_function=embeddings,
)

# RDS for MySQL
from langchain_volcengine_mysql import mysql
mysql.configure(
    host="rds-host.example.com",
    port=3306,
    user="admin",
    password="***",
    database="app_db",
    table_name="vectors",
    embedding_function=embeddings,
)
```

For full provisioning steps and pricing, refer to Volcano Engine official docs.

## API Reference

### Submodules

- `langchain_volcengine_mysql.vedb`:
  - `vector_store`: Attribute to get a configured `VectorStore` instance.
  - `retriever`: Attribute to get a configured `VectorStoreRetriever`.
  - `configure(**config)`: Sets the default configuration for the module.
  - `set_embedding(embedding_function)`: Sets the embedding function.

- `langchain_volcengine_mysql.mysql`:
  - `vector_store`: Attribute to get a configured `VectorStore` instance.
  - `retriever`: Attribute to get a configured `VectorStoreRetriever`.
  - `configure(**config)`: Sets the default configuration for the module.
  - `set_embedding(embedding_function)`: Sets the embedding function.


## Advanced Usage

### Using the Retriever with Chains

The retriever can be seamlessly integrated into LangChain chains.

```python
from langchain.chains import RetrievalQA
from langchain_community.llms import FakeStreamingLLM

# Assuming `mysql.retriever` is already configured
retriever = mysql.retriever

# Create a QA chain
qa_chain = RetrievalQA.from_chain_type(
    llm=FakeStreamingLLM(),
    chain_type="stuff",
    retriever=retriever,
)

# Run the chain
question = "What is an example sentence?"
response = qa_chain.run(question)
print(response)
```

### Schema and Index Management (RDS for MySQL)

The `RDS for MySQL` vector store provides helper methods to manage the database schema and vector index.

```python
# Create the table and HNSW index
vector_store.create_schema(
    table_name="my_documents",
    vector_size=1024,
    algorithm_params={"distance": "l2", "M": 16, "ef_construction": 100},
)

# Drop the index
vector_store.drop_index()

# Drop the table
vector_store.drop_table()
```

## Troubleshooting

- **`ConfigError`**: Raised if required configuration parameters are missing when accessing `vector_store` or `retriever`. Ensure you have called `configure()` with all necessary parameters.
- **Connection Issues**: Verify that the host, port, user, password, and database are correct and that the network connection to the database is allowed.
- **veDB Dependencies**: The veDB adapter relies on the `vedbsearch` client library. If you encounter issues, ensure it is correctly installed and configured in your environment.

## Security

If you discover a potential security issue in this project, please notify ByteDance Security via our [security center](https://security.bytedance.com/src) or by emailing [sec@bytedance.com](mailto:sec@bytedance.com). Please do not create a public GitHub issue.

## Code of Conduct

Please see the [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) file for details.

## Contributing

Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for details.

## License

This project is licensed under the [Apache-2.0 License](LICENSE).
