Metadata-Version: 2.4
Name: yukisdb
Version: 1.0.1
Summary: ⚡ Official Python SDK & Developer CLI for YukisDB — Unified Cloud NoSQL Database, 2GB Object Storage with Zero Egress Fees & AI Vector Search BaaS
Home-page: https://yukisdb.yukiapi.site
Author: SUDEEPBOTS
Author-email: support@yukiapi.site
Project-URL: Homepage, https://yukisdb.yukiapi.site
Project-URL: Documentation, https://yukisdb.yukiapi.site/docs
Project-URL: OpenAPI Specification, https://yukisdb.yukiapi.site/openapi.json
Project-URL: LLMs Knowledge, https://yukisdb.yukiapi.site/llms.txt
Project-URL: Source Code, https://github.com/SUDEEPBOTS/yukisdb
Project-URL: Issue Tracker, https://github.com/SUDEEPBOTS/yukisdb/issues
Keywords: yukisdb,database,nosql,document-database,cloud-database,baas,backend-as-a-service,object-storage,storage,s3-alternative,vector-database,vector-search,embeddings,rag,ai-agent,ai-memory,mcp,model-context-protocol,claude-desktop,cursor,fastapi,json-db,zero-egress,developer-tools,cli,yukiapi,sudeepbots
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<div align="center">

# ⚡ YukisDB — Unified Developer Cloud BaaS
### Sub-millisecond NoSQL JSON Database • 2GB Object Storage (Zero Egress Bills) • AI Vector Memory • Native MCP 2024-11-05

[![PyPI version](https://img.shields.io/pypi/v/yukisdb.svg?color=blue&style=for-the-badge)](https://pypi.org/project/yukisdb/)
[![Python Versions](https://img.shields.io/pypi/pyversions/yukisdb.svg?style=for-the-badge)](https://pypi.org/project/yukisdb/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Datacenter](https://img.shields.io/badge/Datacenter-Singapore%20AP--Southeast-brightgreen?style=for-the-badge)](https://yukisdb.yukiapi.site)
[![MCP Protocol](https://img.shields.io/badge/MCP-2024--11--05-blueviolet?style=for-the-badge)](https://yukisdb.yukiapi.site/mcp)

[🌐 Web Portal](https://yukisdb.yukiapi.site) • [📖 Documentation](https://yukisdb.yukiapi.site/docs) • [📜 OpenAPI 3.1 Spec](https://yukisdb.yukiapi.site/openapi.json) • [🤖 Agent LLMs.txt](https://yukisdb.yukiapi.site/llms.txt) • [💬 Support](https://yukisdb.yukiapi.site/contact)

</div>

---

## 🌟 Why YukisDB?

**YukisDB** (hosted on [yukiapi.site](https://yukisdb.yukiapi.site) by **SUDEEPBOTS**) is an all-in-one developer cloud backend engine built from the ground up for modern full-stack web apps, autonomous AI agents, and developer toolchains:

- 🚀 **Sub-millisecond NoSQL JSON Store:** Ultra-fast document CRUD, flexible filtering, aggregation pipelines, and automatic schema indexing.
- 📦 **2GB Object Storage with Zero Egress Billing:** Upload datasets, videos, model weights, and media files up to 2 GB per file with instant HTTP 206 partial streaming and $0 bandwidth bills.
- 🧠 **AI Vector Memory & Semantic Search:** Native nearest-neighbor cosine similarity search for long-term agent memory and RAG context pipelines.
- 🤖 **Model Context Protocol (MCP 2024-11-05):** Direct Streamable HTTP & SSE transport for Claude Desktop, Cursor AI, Windsurf, and AutoGPT.
- 🧪 **Zero-Friction Sandbox Mode:** Test persistence and queries at `/api/v1/sandbox/insert` without mandatory account registration or credit cards.
- 🔒 **Enterprise-Grade Security:** SHA-256 one-way hashed API keys, CIDR IP whitelist security, TLS 1.3 in-flight encryption, and AES-256 disk encryption at rest.

---

## 📦 Installation

Single command gives you both the **Python SDK** (`import yukisdb`) and the **Developer CLI** (`yukisdb` command):

```bash
pip install yukisdb
```

---

## 💻 Developer CLI Quickstart

Run `yukisdb` directly in your terminal:

```bash
# 1. Check Singapore Cluster Health & Telemetry
$ yukisdb health

# 2. View Developer Free Tier Quotas & Specs
$ yukisdb tier

# 3. Test Zero-Auth Sandbox Document Insert
$ yukisdb sandbox insert '{"task": "Evaluate YukisDB", "status": "completed"}'

# 4. Query Sandbox Documents
$ yukisdb sandbox find '{"status": "completed"}'

# 5. Generate Instant Ephemeral API Key for AI Agents
$ yukisdb anonymous-key

# 6. Authenticated Database Operations (Export your API Key)
$ export YUKISDB_API_KEY="ydb_live_your_key_here"

# Insert Document
$ yukisdb insert users '{"name": "Sudeep", "role": "admin", "skills": ["python", "ai"]}'

# Find Documents with Query
$ yukisdb find users '{"role": "admin"}'

# Upload 2GB File to Object Storage
$ yukisdb upload model_weights.pt custom-slug-2026

# List Stored Files
$ yukisdb list-files

# Start Local MCP stdio Bridge for Claude Desktop / Cursor
$ yukisdb mcp
```

---

## 🐍 Python SDK Guide

### 1. Initialize Client

```python
from yukisdb import YukisDB

# Automatically reads YUKISDB_API_KEY from environment if not passed explicitly
db = YukisDB(api_key="ydb_live_your_api_key_here")
```

### 2. NoSQL Document Persistence (CRUD)

```python
# Insert a new document
user = db.collection("users").insert({
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "tier": "developer",
    "active": True
})
doc_id = user["id"]
print(f"✅ Document created with ID: {doc_id}")

# Find documents with JSON filter
active_devs = db.collection("users").find({"tier": "developer", "active": True})
print("Found developers:", active_devs)

# Get document by ID
doc = db.collection("users").get(doc_id)

# Update document fields
db.collection("users").update(doc_id, {"tier": "enterprise"})

# Run Aggregation Pipeline ($match, $group, $sort)
stats = db.collection("users").aggregate([
    {"$match": {"active": True}},
    {"$group": {"_id": "$tier", "total": {"$sum": 1}}}
])

# Delete document
db.collection("users").delete(doc_id)
```

### 3. AI Vector Embeddings Search (Cosine Similarity)

```python
# Query semantic nearest neighbors for agent memory
results = db.collection("agent_memory").vector_search(
    vector=[0.124, -0.451, 0.882, 0.051],
    field="embedding",
    top_k=5
)

for item in results:
    print(f"Match: {item['title']} | Similarity Score: {item['_score']}")
```

### 4. 2GB Object Storage (Zero Egress Bandwidth Bills)

```python
# Upload any binary file up to 2GB with high-speed CDN URL
file_info = db.storage.upload(
    file_path_or_bytes="4k_dataset_video.mp4",
    custom_slug="dataset-singapore-2026"
)

print(f"Uploaded! Public Streaming CDN URL: {file_info['url']}")

# List all objects in storage
objects = db.storage.list()
print("Tenant files:", len(objects))
```

### 5. Zero-Auth Sandbox (Instant Prototyping)

```python
# No API key needed for sandbox operations
sandbox_doc = db.sandbox.insert({"experiment": "LLM agent autonomous test"})
print("Persisted into sandbox:", sandbox_doc)
```

---

## 🤖 Model Context Protocol (MCP 2024-11-05) Setup

YukisDB provides first-class support for **Model Context Protocol (MCP)**. Connect Claude Desktop, Cursor AI, Windsurf, or AutoGPT directly:

### Claude Desktop Configuration (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "yukisdb": {
      "command": "yukisdb",
      "args": ["mcp"],
      "env": {
        "YUKISDB_API_KEY": "ydb_live_your_key_here"
      }
    }
  }
}
```

### Direct Streamable HTTP & SSE Transport:
- **Streamable HTTP Endpoint:** `https://yukisdb.yukiapi.site/mcp`
- **SSE Stream Endpoint:** `https://yukisdb.yukiapi.site/mcp/sse`
- **MCP Manifest:** `https://yukisdb.yukiapi.site/.well-known/mcp/manifest.json`

### Supported MCP Tools:
- `insert_document`: Save JSON document memory.
- `find_documents`: Query documents with JSON filters.
- `get_document`: Retrieve document by ID.
- `update_document`: Update document attributes.
- `delete_document`: Delete document by ID.
- `aggregate_documents`: Multi-stage aggregation pipelines.
- `vector_search`: Cosine similarity nearest-neighbor semantic search.
- `upload_file`: Upload files & datasets (up to 2GB).
- `list_files`: List tenant storage files.
- `get_cluster_health`: Real-time datacenter status.
- `get_tier_policy`: Free tier quotas & parameters.

---

## ⚙️ Architecture & Reliability

| Specification | Value |
|---|---|
| **Datacenter Region** | Singapore (AP-Southeast), Tier-1 Redundant Network |
| **Document Query Latency** | Sub-millisecond indexed NVMe SSD Lookups |
| **Object File Size Limit** | Up to **2 GB per file** (Unlimited total files) |
| **Bandwidth Policy** | **Free Unlimited Egress** for Developer Accounts |
| **Encryption In-Flight** | TLS 1.3 Strict HTTPS Transport |
| **Encryption At-Rest** | AES-256 Disk Encryption |
| **Key Security** | SHA-256 One-Way Hashing with Salt |
| **Rate Limit Standard** | RFC 6585 / IETF RateLimit Headers (`RateLimit-Limit: 1200`) |
| **Error Handling Model** | RFC 9457 Problem Details (`application/problem+json`) |
| **API Versioning** | Explicit `/api/v1/...` with RFC 8594 Sunset Guarantees |

---

## 🔗 Developer Resources Index (yukiapi.site)

- 🌐 **Portal & Dashboard:** [https://yukisdb.yukiapi.site](https://yukisdb.yukiapi.site)
- 📖 **Developer Documentation:** [https://yukisdb.yukiapi.site/docs](https://yukisdb.yukiapi.site/docs)
- 🔐 **Authentication & Scopes:** [https://yukisdb.yukiapi.site/docs/auth](https://yukisdb.yukiapi.site/docs/auth)
- ⚡ **Webhooks & Events:** [https://yukisdb.yukiapi.site/docs/webhooks](https://yukisdb.yukiapi.site/docs/webhooks)
- 📜 **OpenAPI 3.1 Spec (JSON):** [https://yukisdb.yukiapi.site/openapi.json](https://yukisdb.yukiapi.site/openapi.json)
- 📄 **OpenAPI 3.1 Spec (YAML):** [https://yukisdb.yukiapi.site/openapi.yaml](https://yukisdb.yukiapi.site/openapi.yaml)
- 🤖 **LLMs Reference (llms.txt):** [https://yukisdb.yukiapi.site/llms.txt](https://yukisdb.yukiapi.site/llms.txt)
- 📚 **Full Reference (llms-full.txt):** [https://yukisdb.yukiapi.site/llms-full.txt](https://yukisdb.yukiapi.site/llms-full.txt)
- ⏳ **Deprecation & Versioning Policy:** [https://yukisdb.yukiapi.site/deprecation](https://yukisdb.yukiapi.site/deprecation)
- 🗺️ **Sitemap:** [https://yukisdb.yukiapi.site/sitemap.xml](https://yukisdb.yukiapi.site/sitemap.xml)
- 🐙 **GitHub Repository:** [https://github.com/SUDEEPBOTS/yukisdb](https://github.com/SUDEEPBOTS/yukisdb)

---

## 📄 License

YukisDB is licensed under the [MIT License](https://github.com/SUDEEPBOTS/yukisdb/blob/main/LICENSE).

Copyright © 2026 SUDEEPBOTS. All rights reserved.
