synadb 0.1.0__tar.gz

synadb-0.1.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: synadb
+Version: 0.1.0
+Summary: Python wrapper for Syna embedded database
+Author: Syna Team
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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
+Requires-Python: >=3.8
+Requires-Dist: numpy>=1.21.0
+Provides-Extra: ml
+Requires-Dist: torch>=2.0.0; extra == "ml"
+Requires-Dist: datasets>=2.14.0; extra == "ml"
+Requires-Dist: transformers>=4.30.0; extra == "ml"
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.3.0; extra == "pandas"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0.0; extra == "dev"
+Dynamic: author
+Dynamic: classifier
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

synadb-0.1.0/README.md

@@ -0,0 +1,294 @@
+# Syna Python Demos
+
+This directory contains Python examples demonstrating Syna's Python wrapper and integrations.
+
+## Prerequisites
+
+### 1. Build the Syna Library
+
+```bash
+# From repository root
+cargo build --release
+```
+
+### 2. Install Python Dependencies
+
+```bash
+cd demos/python
+pip install -r requirements.txt
+```
+
+### 3. Set Library Path (if needed)
+
+```bash
+# Linux
+export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:../../target/release
+
+# macOS
+export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:../../target/release
+
+# Or copy the library to this directory
+cp ../../target/release/libsynadb.so .  # Linux
+cp ../../target/release/libsynadb.dylib .  # macOS
+```
+
+## Running Demos
+
+```bash
+cd demos/python
+
+# Basic usage
+python basic_usage.py
+
+# NumPy integration
+python numpy_integration.py
+
+# Pandas integration
+python pandas_integration.py
+
+# Async operations
+python async_operations.py
+
+# Context manager patterns
+python context_manager.py
+
+# RL experience replay
+python rl_experience_demo.py
+```
+
+## Demo Descriptions
+
+| Demo | File | Description |
+|------|------|-------------|
+| Basic Usage | `basic_usage.py` | Library loading, CRUD operations, error handling |
+| NumPy | `numpy_integration.py` | Zero-copy tensor extraction to numpy arrays |
+| Pandas | `pandas_integration.py` | DataFrame loading and time-series indexing |
+| Async | `async_operations.py` | Non-blocking operations with asyncio |
+| Context Manager | `context_manager.py` | Resource management with `with` statements |
+| RL Experience | `rl_experience_demo.py` | Reinforcement learning experience replay |
+
+## Demo Details
+
+### 1. Basic Usage (`basic_usage.py`)
+
+Comprehensive introduction to the Python wrapper:
+- Library loading and path discovery
+- Database open/close patterns
+- All write operations (put_float, put_int, put_text, put_bytes)
+- All read operations (get_float, get_int, get_text, get_bytes)
+- Delete operations and key listing
+- Error handling patterns
+- Database compaction
+- Data persistence
+
+### 2. NumPy Integration (`numpy_integration.py`)
+
+ML-focused tensor operations:
+- Extract history as numpy arrays
+- Zero-copy when possible
+- Memory efficiency comparison
+- Batch operations
+
+```python
+from Syna import synadb
+import numpy as np
+
+with synadb("sensors.db") as db:
+    # Store time-series data
+    for temp in temperatures:
+        db.put_float("sensor/temp", temp)
+    
+    # Extract as numpy array for ML
+    tensor = db.get_history_tensor("sensor/temp")
+    print(f"Shape: {tensor.shape}, dtype: {tensor.dtype}")
+```
+
+### 3. Pandas Integration (`pandas_integration.py`)
+
+DataFrame operations:
+- Load time-series into DataFrame with timestamp index
+- Store DataFrame back to Syna
+- Query patterns using pandas
+
+```python
+# Load to DataFrame
+df = db.to_dataframe("sensor/*")
+
+# Store from DataFrame
+db.from_dataframe(df, key_prefix="data/")
+```
+
+### 4. Async Operations (`async_operations.py`)
+
+Non-blocking database access:
+- Uses `asyncio` with thread pool executor
+- Concurrent async reads
+- Non-blocking writes
+
+```python
+import asyncio
+from Syna import synadb
+
+async def async_write(db, key, value):
+    loop = asyncio.get_event_loop()
+    await loop.run_in_executor(None, db.put_float, key, value)
+```
+
+### 5. Context Manager (`context_manager.py`)
+
+Resource management patterns:
+- `with` statement usage
+- Automatic cleanup on exception
+- Nested context managers for multiple DBs
+
+```python
+# Recommended pattern
+with synadb("my.db") as db:
+    db.put_float("key", 3.14)
+# Database automatically closed here
+```
+
+### 6. RL Experience Replay (`rl_experience_demo.py`)
+
+Reinforcement learning patterns:
+- Store experience tuples (state, action, reward, next_state)
+- Efficient batch sampling
+- Prioritized replay support
+
+## Python Wrapper API
+
+### synadb Class
+
+```python
+from Syna import synadb, SynaError
+
+# Open database
+db = synadb("my.db")
+
+# Write operations
+offset = db.put_float("key", 3.14)
+offset = db.put_int("key", 42)
+offset = db.put_text("key", "hello")
+offset = db.put_bytes("key", b"\x00\x01\x02")
+
+# Read operations
+value = db.get_float("key")      # Optional[float]
+value = db.get_int("key")        # Optional[int]
+value = db.get_text("key")       # Optional[str]
+value = db.get_bytes("key")      # Optional[bytes]
+
+# History extraction (for ML)
+tensor = db.get_history_tensor("key")  # np.ndarray
+
+# Key operations
+exists = db.exists("key")        # bool
+keys = db.keys()                 # List[str]
+db.delete("key")
+
+# Maintenance
+db.compact()
+db.close()
+```
+
+### Error Handling
+
+```python
+from Syna import synadb, SynaError
+
+try:
+    with synadb("my.db") as db:
+        db.put_float("key", 3.14)
+except SynaError as e:
+    print(f"Error {e.code}: {e.message}")
+```
+
+### Error Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Generic error |
+| -1 | Database not found in registry |
+| -2 | Invalid path or UTF-8 |
+| -3 | I/O error |
+| -4 | Serialization error |
+| -5 | Key not found |
+| -6 | Type mismatch |
+| -7 | Empty key not allowed |
+| -8 | Key too long |
+| -100 | Internal panic |
+
+## Testing
+
+Run the test suite:
+
+```bash
+cd demos/python
+pytest tests/ -v
+```
+
+Run with hypothesis for property-based tests:
+
+```bash
+pytest tests/ -v --hypothesis-show-statistics
+```
+
+## File Structure
+
+```
+demos/python/
+├── Syna/               # Python package
+│   ├── __init__.py
+│   ├── wrapper.py          # Main synadb class
+│   └── experience.py       # RL experience helpers
+├── tests/                  # Test suite
+│   ├── test_wrapper.py
+│   └── test_pandas.py
+├── basic_usage.py          # Basic operations demo
+├── numpy_integration.py    # NumPy demo
+├── pandas_integration.py   # Pandas demo
+├── async_operations.py     # Async demo
+├── context_manager.py      # Context manager demo
+├── rl_experience_demo.py   # RL demo
+├── requirements.txt        # Dependencies
+├── setup.py               # Package setup
+└── pytest.ini             # Test configuration
+```
+
+## Troubleshooting
+
+### Library Not Found
+
+```
+OSError: libsynadb.so: cannot open shared object file
+```
+
+Solution: Set `LD_LIBRARY_PATH` or copy the library:
+```bash
+export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:../../target/release
+# or
+cp ../../target/release/libsynadb.so .
+```
+
+### Import Error
+
+```
+ModuleNotFoundError: No module named 'Syna'
+```
+
+Solution: Run from the `demos/python` directory or install the package:
+```bash
+cd demos/python
+pip install -e .
+```
+
+### NumPy Version Mismatch
+
+```
+RuntimeWarning: numpy.dtype size changed
+```
+
+Solution: Upgrade numpy:
+```bash
+pip install --upgrade numpy
+```
+

synadb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

synadb-0.1.0/setup.py

@@ -0,0 +1,40 @@
+"""Setup script for Syna Python wrapper."""
+
+from setuptools import setup, find_packages
+
+setup(
+    name="synadb",
+    version="0.1.0",
+    description="Python wrapper for Syna embedded database",
+    author="Syna Team",
+    packages=find_packages(),
+    python_requires=">=3.8",
+    install_requires=[
+        "numpy>=1.21.0",
+    ],
+    extras_require={
+        "ml": [
+            "torch>=2.0.0",
+            "datasets>=2.14.0",
+            "transformers>=4.30.0",
+        ],
+        "pandas": [
+            "pandas>=1.3.0",
+        ],
+        "dev": [
+            "pytest>=7.0.0",
+            "hypothesis>=6.0.0",
+        ],
+    },
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+    ],
+)
+

synadb-0.1.0/synadb/__init__.py

@@ -0,0 +1,30 @@
+"""
+Syna Python Wrapper
+
+A high-level Python interface for the Syna embedded database.
+
+Example:
+    >>> from Syna import SynaDB
+    >>> with SynaDB("my.db") as db:
+    ...     db.put_float("temperature", 23.5)
+    ...     print(db.get_float("temperature"))
+    23.5
+
+For RL experience collection:
+    >>> from Syna import ExperienceCollector
+    >>> collector = ExperienceCollector("exp.db", machine_id="gpu_server_1")
+    >>> collector.log_transition(state, action, reward, next_state)
+"""
+
+from .wrapper import SynaDB, SynaError
+from .experience import ExperienceCollector, Transition, SessionContext
+
+__version__ = "0.1.0"
+__all__ = [
+    "SynaDB",
+    "SynaError",
+    "ExperienceCollector",
+    "Transition",
+    "SessionContext",
+]
+