smartkdb 4.0.0

SmartKDB – Cognitive & AI-Training-Aware Embedded Database

SmartKDB 🧠

The Cognitive, AI-Native Embedded Database for Python.

SmartKDB is a next-generation embedded database engine written in pure Python. It goes beyond storing data—it understands it. With built-in vector search, a cognitive agent you can chat with, and an AI training hub, SmartKDB is designed for modern AI engineering.

---

🚀 Key Features

1. Core Engine

• Local-First & Embedded: No servers to manage. Just a file in your project.
• Hybrid Storage: Supports structured tables and unstructured JSON documents.
• Secure: Built-in Role-Based Access Control (RBAC).

2. Cognitive Intelligence (v4)

• 💬 Chat with Data: Ask db.chat("How is the system health?") to get answers.
• 🔮 Predictive Engine: Forecasts which tables will be "hot" based on usage patterns.
• 🧠 Knowledge Graph: Automatically tracks relationships between your data entities.

3. AI Training Hub (v4)

• 🎓 Dataset Management: Create, version, and split datasets (Train/Test/Val) natively.
• 📉 Experiment Tracking: Log model training metrics (loss, accuracy) directly into the DB.

4. Self-Learning (v3)

• ⚡ Auto-Tuning: The "Brain" learns from your queries and automatically creates indexes.
• 🔍 Vector Search: Store embeddings and perform similarity search locally.
• 🗣️ Semantic Query: Query using natural language: db.semantic_query("users", "engineers over 30").

---

📦 Installation

pip install smartkdb

---

📖 Official Guide

1. Getting Started

Initialize the database and create your first table.

from kdb import SmartKDB

# Initialize DB (creates a folder 'mydb.kdb')
db = SmartKDB("mydb.kdb")

# Create a user (First time setup)
db.auth.create_user("admin", "secret_pass", "admin")
db.login("admin", "secret_pass")

# Create a table
users = db.create_table("users")

# Insert data
users.insert({"name": "Alice", "age": 30, "role": "Engineer"})
users.insert({"name": "Bob", "age": 24, "role": "Designer"})

# Simple Query
results = users.query().where("age", ">", 25).execute()
print(results)

2. Cognitive Features (Chat & Agent)

SmartKDB v4 includes an embedded agent. You don't need to write complex queries for metadata; just ask.

# Chat with your DB
response = db.chat("Which tables are most active?")
print(response['message'])

# Ask for recommendations
response = db.chat("Do you suggest any indexes?")
print(response['actions'])

3. AI & Vector Search

Store vector embeddings (lists of floats) and search by similarity.

# Enable vector index on a field
db.enable_vector_index("products", "description")

# Perform Semantic Search (Natural Language)
# This uses the internal vector engine to find similar items
results = db.vector_search("products", "comfortable running shoes", "description")

4. AI Training Hub

Use SmartKDB to manage your Machine Learning lifecycle.

Managing Datasets

# Create a dataset from the 'users' table, filtering for Engineers
db.datasets.create_dataset(
    name="engineer_ages", 
    table="users", 
    filter_query={"role": "Engineer"}
)

# Define splits (80% Train, 10% Val, 10% Test)
db.datasets.define_split("engineer_ages", 0.8, 0.1, 0.1)

Logging Experiments

# Start a training session
session_id = db.training_logger.start_session(
    model_name="age_predictor", 
    dataset_name="engineer_ages", 
    config={"learning_rate": 0.01}
)

# Log metrics during training
db.training_logger.log_metric(session_id, step=1, metrics={"loss": 0.5})
db.training_logger.log_metric(session_id, step=2, metrics={"loss": 0.3})

# End session
db.training_logger.end_session(session_id, status="success")

5. Dashboard & Management

SmartKDB comes with a built-in HTML dashboard.

1. Navigate to your database folder (mydb.kdb).
2. Open kdb_config.html in any web browser.
3. Features:
   • Brain Center: View learned patterns and feedback.
   • Cognitive Engine: Chat interface with the Agent.
   • Training Hub: View datasets and experiment logs.
   • Config: Manage users and auto-indexing settings.

---

🔧 CLI Reference

SmartKDB includes a command-line tool.

# Initialize a new DB in the current directory
smartkdb init

# Check status of an existing DB
smartkdb status

# Open an interactive SQL-like shell (Coming Soon)
smartkdb shell

---

🛡️ Architecture

SmartKDB is Local-First. All data is stored in the directory you specify.

• data/: Raw data blocks (append-only).
• indexes/: B-Tree and Hash indexes.
• kdb_brain.json: The learned model of your data usage.
• kdb_knowledge.json: The semantic knowledge graph.
• kdb_training.json: Logs of your ML experiments.

---

License: MIT
Author: Alhdrawi