| Name | liath JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | An AI-powered database system with key-value storage, vector search, and AI capabilities |
| upload_time | 2025-08-22 13:34:42 |
| maintainer | None |
| docs_url | None |
| author | Dipankar Sarkar |
| requires_python | <3.13,>=3.11 |
| license | MIT |
| keywords |
database
ai
llm
key-value
lua
vector-search
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 🚀 Liath: Your AI-Powered Database System
> Liath is a next-generation database system that combines the power of key-value storage, vector search, and AI capabilities into one flexible platform. Built on RocksDB/LevelDB with Lua as its query language, it's designed for developers who want to build AI-powered applications quickly and efficiently.
[](https://badge.fury.io/py/liath)
[](https://opensource.org/licenses/MIT)
## ✨ Key Features
Liath comes packed with powerful features to help you build AI-powered applications. Here's a quick overview:
- 🔌 **Pluggable Storage**: Choose between RocksDB and LevelDB
- 📝 **Lua Query Language**: Write powerful queries with familiar syntax
- 🧩 **Plugin Architecture**: Extend functionality with custom plugins
- 🔍 **Vector Search**: Built-in vector database capabilities
- 🤖 **AI Integration**: Direct access to language models
- 📊 **Embedding Generation**: Create and manage text embeddings
- 📁 **File Operations**: Built-in file storage and retrieval
- 🏷️ **Namespaces**: Isolate data and operations
- 💾 **Transaction Support**: ACID compliant (RocksDB)
- 🔐 **User Authentication**: Secure user management
- 🌐 **CLI & HTTP API**: Multiple ways to interact
- 💾 **Backup & Restore**: Keep your data safe
- ⚡ **Query Caching**: Optimize performance
- 📈 **Monitoring**: Track system performance
- 🔄 **Connection Pooling**: Handle high concurrency
> 📚 For detailed information about each feature, check out our [Features Documentation](FEATURES.md)
## 🛠️ Installation
### As a Library
```bash
pip install liath
```
### From Source
1. **Prerequisites**
- Python 3.11 or higher
- Poetry package manager
2. **Install Poetry**
```bash
pip install poetry
```
3. **Clone & Setup**
```bash
git clone https://github.com/nudgelang/liath.git
cd liath
poetry install
```
4. **Create Directory Structure**
```bash
mkdir -p data/default/{files,luarocks} plugins
```
5. **Install Lua Dependencies**
```bash
./liath/setup_luarocks.sh
```
## 📦 Usage
### As a Library (Embedded Mode)
```python
from liath import EmbeddedLiath
# Create an embedded database instance
db = EmbeddedLiath(data_dir="./my_data", storage_type="auto")
# Basic operations
db.put("key", "value")
retrieved_value = db.get("key")
print(retrieved_value) # Output: value
# Execute Lua queries
result = db.execute_lua('return db:get("key")')
print(result) # Output: value
# Switch namespaces
db.set_namespace("my_namespace")
db.put("namespaced_key", "namespaced_value")
# Close the database when done
db.close()
```
### CLI Mode
```bash
liath-cli --storage auto
```
### Server Mode
```bash
liath-server --storage auto --host 0.0.0.0 --port 5000
```
### Basic Operations
```lua
-- Create user and login
create_user username password
login username password
-- Create and use namespace
create_namespace my_namespace
use my_namespace
-- Basic queries
query return db:put("key", "value")
query return db:get("key")
```
## 📦 Using LuaRocks Packages
Liath supports LuaRocks packages in your queries. Here's how:
1. **Install a Package**
```bash
luarocks install --tree=./data/namespaces/your_namespace package_name
```
2. **Use in Queries**
```lua
local json = db:require("cjson")
return json.encode({key = "value"})
```
### Example: HTTP Requests with LuaSocket
```lua
local http = db:require("socket.http")
local body, code = http.request("http://example.com")
return {body = body, status_code = code}
```
## 🔄 Storage Options
Choose your storage backend based on your needs:
| Feature | RocksDB | LevelDB |
|---------|---------|---------|
| Performance | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| Transactions | ✅ | ❌ |
| Column Families | ✅ | ❌ |
| Complexity | Medium | Low |
## 🔧 API Reference
### EmbeddedLiath Class
The `EmbeddedLiath` class provides a Pythonic interface for interacting with the database.
#### Constructor
```python
db = EmbeddedLiath(data_dir="./data", storage_type="auto")
```
Parameters:
- `data_dir` (str): Directory to store database files
- `storage_type` (str): Storage backend ('auto', 'rocksdb', or 'leveldb')
#### Methods
##### `put(key, value)`
Store a key-value pair in the database.
##### `get(key)`
Retrieve a value from the database.
##### `delete(key)`
Delete a key-value pair from the database.
##### `execute_lua(query)`
Execute a Lua query.
##### `set_namespace(namespace)`
Switch to a different namespace.
##### `create_user(username, password)`
Create a new user.
##### `authenticate_user(username, password)`
Authenticate a user.
##### `list_namespaces()`
List all namespaces.
##### `close()`
Close the database connection.
### Direct Database Access
For more advanced usage, you can access the underlying `Database` class directly:
```python
from liath import Database
db = Database(data_dir="./data", storage_type="auto")
# ... use database methods directly
```
## 🧩 Extending Liath
Create custom plugins by:
1. Adding a new Python file in `plugins/`
2. Inheriting from `PluginBase`
3. Implementing required methods
### Example Plugin
```python
from liath.plugin_base import PluginBase
class MyPlugin(PluginBase):
@property
def name(self):
return "myplugin"
def initialize(self, context):
self.namespace = context['namespace']
def get_lua_interface(self):
return {
'my_function': self.lua_callable(self.my_function)
}
def my_function(self, arg1, arg2):
# Your plugin logic here
return f"Processed {arg1} and {arg2}"
```
## 📦 Using LuaRocks Packages
Liath supports LuaRocks packages in your queries. Here's how:
1. **Install a Package**
```bash
luarocks install --tree=./data/namespaces/your_namespace package_name
```
2. **Use in Queries**
```lua
local json = db:require("cjson")
return json.encode({key = "value"})
```
### Example: HTTP Requests with LuaSocket
```lua
local http = db:require("socket.http")
local body, code = http.request("http://example.com")
return {body = body, status_code = code}
```
## 🤝 Contributing
We welcome contributions! Feel free to:
- Submit pull requests
- Report bugs
- Suggest features
- Improve documentation
## 📄 License
MIT License - See [LICENSE](LICENSE) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "liath",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.11",
"maintainer_email": null,
"keywords": "database, ai, llm, key-value, lua, vector-search",
"author": "Dipankar Sarkar",
"author_email": "me@dipankar.name",
"download_url": "https://files.pythonhosted.org/packages/a2/87/17282a5b3286cffcab5ed584ba3a22e6d23dc6498a27185578a51273abaf/liath-0.1.0.tar.gz",
"platform": null,
"description": "# \ud83d\ude80 Liath: Your AI-Powered Database System\n\n> Liath is a next-generation database system that combines the power of key-value storage, vector search, and AI capabilities into one flexible platform. Built on RocksDB/LevelDB with Lua as its query language, it's designed for developers who want to build AI-powered applications quickly and efficiently.\n\n[](https://badge.fury.io/py/liath)\n[](https://opensource.org/licenses/MIT)\n\n## \u2728 Key Features\n\nLiath comes packed with powerful features to help you build AI-powered applications. Here's a quick overview:\n\n- \ud83d\udd0c **Pluggable Storage**: Choose between RocksDB and LevelDB\n- \ud83d\udcdd **Lua Query Language**: Write powerful queries with familiar syntax\n- \ud83e\udde9 **Plugin Architecture**: Extend functionality with custom plugins\n- \ud83d\udd0d **Vector Search**: Built-in vector database capabilities\n- \ud83e\udd16 **AI Integration**: Direct access to language models\n- \ud83d\udcca **Embedding Generation**: Create and manage text embeddings\n- \ud83d\udcc1 **File Operations**: Built-in file storage and retrieval\n- \ud83c\udff7\ufe0f **Namespaces**: Isolate data and operations\n- \ud83d\udcbe **Transaction Support**: ACID compliant (RocksDB)\n- \ud83d\udd10 **User Authentication**: Secure user management\n- \ud83c\udf10 **CLI & HTTP API**: Multiple ways to interact\n- \ud83d\udcbe **Backup & Restore**: Keep your data safe\n- \u26a1 **Query Caching**: Optimize performance\n- \ud83d\udcc8 **Monitoring**: Track system performance\n- \ud83d\udd04 **Connection Pooling**: Handle high concurrency\n\n> \ud83d\udcda For detailed information about each feature, check out our [Features Documentation](FEATURES.md)\n\n## \ud83d\udee0\ufe0f Installation\n\n### As a Library\n```bash\npip install liath\n```\n\n### From Source\n1. **Prerequisites**\n - Python 3.11 or higher\n - Poetry package manager\n\n2. **Install Poetry**\n ```bash\n pip install poetry\n ```\n\n3. **Clone & Setup**\n ```bash\n git clone https://github.com/nudgelang/liath.git\n cd liath\n poetry install\n ```\n\n4. **Create Directory Structure**\n ```bash\n mkdir -p data/default/{files,luarocks} plugins\n ```\n\n5. **Install Lua Dependencies**\n ```bash\n ./liath/setup_luarocks.sh\n ```\n\n## \ud83d\udce6 Usage\n\n### As a Library (Embedded Mode)\n```python\nfrom liath import EmbeddedLiath\n\n# Create an embedded database instance\ndb = EmbeddedLiath(data_dir=\"./my_data\", storage_type=\"auto\")\n\n# Basic operations\ndb.put(\"key\", \"value\")\nretrieved_value = db.get(\"key\")\nprint(retrieved_value) # Output: value\n\n# Execute Lua queries\nresult = db.execute_lua('return db:get(\"key\")')\nprint(result) # Output: value\n\n# Switch namespaces\ndb.set_namespace(\"my_namespace\")\ndb.put(\"namespaced_key\", \"namespaced_value\")\n\n# Close the database when done\ndb.close()\n```\n\n### CLI Mode\n```bash\nliath-cli --storage auto\n```\n\n### Server Mode\n```bash\nliath-server --storage auto --host 0.0.0.0 --port 5000\n```\n\n### Basic Operations\n\n```lua\n-- Create user and login\ncreate_user username password\nlogin username password\n\n-- Create and use namespace\ncreate_namespace my_namespace\nuse my_namespace\n\n-- Basic queries\nquery return db:put(\"key\", \"value\")\nquery return db:get(\"key\")\n```\n\n## \ud83d\udce6 Using LuaRocks Packages\n\nLiath supports LuaRocks packages in your queries. Here's how:\n\n1. **Install a Package**\n ```bash\n luarocks install --tree=./data/namespaces/your_namespace package_name\n ```\n\n2. **Use in Queries**\n ```lua\n local json = db:require(\"cjson\")\n return json.encode({key = \"value\"})\n ```\n\n### Example: HTTP Requests with LuaSocket\n\n```lua\nlocal http = db:require(\"socket.http\")\nlocal body, code = http.request(\"http://example.com\")\nreturn {body = body, status_code = code}\n```\n\n## \ud83d\udd04 Storage Options\n\nChoose your storage backend based on your needs:\n\n| Feature | RocksDB | LevelDB |\n|---------|---------|---------|\n| Performance | \u2b50\u2b50\u2b50\u2b50\u2b50 | \u2b50\u2b50\u2b50 |\n| Transactions | \u2705 | \u274c |\n| Column Families | \u2705 | \u274c |\n| Complexity | Medium | Low |\n\n## \ud83d\udd27 API Reference\n\n### EmbeddedLiath Class\n\nThe `EmbeddedLiath` class provides a Pythonic interface for interacting with the database.\n\n#### Constructor\n```python\ndb = EmbeddedLiath(data_dir=\"./data\", storage_type=\"auto\")\n```\n\nParameters:\n- `data_dir` (str): Directory to store database files\n- `storage_type` (str): Storage backend ('auto', 'rocksdb', or 'leveldb')\n\n#### Methods\n\n##### `put(key, value)`\nStore a key-value pair in the database.\n\n##### `get(key)`\nRetrieve a value from the database.\n\n##### `delete(key)`\nDelete a key-value pair from the database.\n\n##### `execute_lua(query)`\nExecute a Lua query.\n\n##### `set_namespace(namespace)`\nSwitch to a different namespace.\n\n##### `create_user(username, password)`\nCreate a new user.\n\n##### `authenticate_user(username, password)`\nAuthenticate a user.\n\n##### `list_namespaces()`\nList all namespaces.\n\n##### `close()`\nClose the database connection.\n\n### Direct Database Access\n\nFor more advanced usage, you can access the underlying `Database` class directly:\n\n```python\nfrom liath import Database\n\ndb = Database(data_dir=\"./data\", storage_type=\"auto\")\n# ... use database methods directly\n```\n\n## \ud83e\udde9 Extending Liath\n\nCreate custom plugins by:\n1. Adding a new Python file in `plugins/`\n2. Inheriting from `PluginBase`\n3. Implementing required methods\n\n### Example Plugin\n```python\nfrom liath.plugin_base import PluginBase\n\nclass MyPlugin(PluginBase):\n @property\n def name(self):\n return \"myplugin\"\n\n def initialize(self, context):\n self.namespace = context['namespace']\n\n def get_lua_interface(self):\n return {\n 'my_function': self.lua_callable(self.my_function)\n }\n\n def my_function(self, arg1, arg2):\n # Your plugin logic here\n return f\"Processed {arg1} and {arg2}\"\n```\n\n## \ud83d\udce6 Using LuaRocks Packages\n\nLiath supports LuaRocks packages in your queries. Here's how:\n\n1. **Install a Package**\n ```bash\n luarocks install --tree=./data/namespaces/your_namespace package_name\n ```\n\n2. **Use in Queries**\n ```lua\n local json = db:require(\"cjson\")\n return json.encode({key = \"value\"})\n ```\n\n### Example: HTTP Requests with LuaSocket\n\n```lua\nlocal http = db:require(\"socket.http\")\nlocal body, code = http.request(\"http://example.com\")\nreturn {body = body, status_code = code}\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Feel free to:\n- Submit pull requests\n- Report bugs\n- Suggest features\n- Improve documentation\n\n## \ud83d\udcc4 License\n\nMIT License - See [LICENSE](LICENSE) for details.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An AI-powered database system with key-value storage, vector search, and AI capabilities",
"version": "0.1.0",
"project_urls": {
"Repository": "https://github.com/skelf-research/liath"
},
"split_keywords": [
"database",
" ai",
" llm",
" key-value",
" lua",
" vector-search"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7fb63cf475de0b919a5b0984183353c7d7f1183e0ebbdb74e2640f3222dc82bd",
"md5": "8aa2561ece42be84833631fa4e90ca70",
"sha256": "8255a3ca7d4b725ef4fd4f2a9390f40200b799f9d48b8ec0c29fa223f760726c"
},
"downloads": -1,
"filename": "liath-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8aa2561ece42be84833631fa4e90ca70",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.11",
"size": 102963,
"upload_time": "2025-08-22T13:34:40",
"upload_time_iso_8601": "2025-08-22T13:34:40.871076Z",
"url": "https://files.pythonhosted.org/packages/7f/b6/3cf475de0b919a5b0984183353c7d7f1183e0ebbdb74e2640f3222dc82bd/liath-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a28717282a5b3286cffcab5ed584ba3a22e6d23dc6498a27185578a51273abaf",
"md5": "f4b1898f7ee143306cda19e4273dc61b",
"sha256": "09a282a3d40549e7949ef63e3c50c5c460d9aea431831f27c769a34f756bb2ec"
},
"downloads": -1,
"filename": "liath-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f4b1898f7ee143306cda19e4273dc61b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.11",
"size": 86625,
"upload_time": "2025-08-22T13:34:42",
"upload_time_iso_8601": "2025-08-22T13:34:42.108191Z",
"url": "https://files.pythonhosted.org/packages/a2/87/17282a5b3286cffcab5ed584ba3a22e6d23dc6498a27185578a51273abaf/liath-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 13:34:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "skelf-research",
"github_project": "liath",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "liath"
}
