sovaria-sdk 0.2.0__tar.gz

sovaria_sdk-0.2.0/.gitignore

@@ -0,0 +1,161 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+!apps/web/src/lib/
+!apps/web/src/lib/**
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+sovaria-env/
+
+# Testing
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Node.js
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnp/
+.pnp.js
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+
+# Build outputs
+dist/
+.next/
+out/
+.turbo/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Docker
+*.log
+.docker/
+
+# Database & Local Dev Data
+infrastructure/local-dev/postgres/
+infrastructure/local-dev/redis/
+infrastructure/local-dev/etcd/
+infrastructure/local-dev/temp-storage/
+*.db
+*.sqlite
+*.sqlite3
+
+# Backups & Archives
+_backup_*/
+*.tar.gz
+*.zip
+
+# Secrets & Credentials
+
+*.key
+*.pem
+*.crt
+secrets/
+credentials/
+
+# Terraform
+.terraform/
+*.tfstate
+*.tfstate.backup
+*.tfvars
+
+# Kubernetes
+*.kubeconfig
+
+# Logs
+logs/
+*.log
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Compiled binaries
+*.exe
+*.dll
+*.dylib
+
+# Generated files
+proto/generated/
+*.pb.go
+*_pb2.py
+*_pb2_grpc.py
+
+# Temporary files
+tmp/
+temp/
+.tmp/
+
+# Coverage reports
+htmlcov/
+.coverage.*
+
+# Compiled documentation
+docs/_build/
+site/
+
+# Jupyter Notebooks
+.ipynb_checkpoints/
+
+# macOS
+.AppleDouble
+.LSOverride
+Icon
+._*
+
+/implementation_md
+
+# dev TLS certs (generated by scripts/gen_grpc_certs.py)
+engines/axis/certs/
+sovaria_data/atlas-rel/atlas_rel.meta.json

sovaria_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.5
+Name: sovaria-sdk
+Version: 0.2.0
+Summary: Python SDK for Sovaria Gateway and Engines
+Project-URL: Homepage, https://sovaria.in
+Project-URL: Documentation, https://docs.sovaria.in/sdk
+Project-URL: Repository, https://github.com/sovaria/sovaria-sdk
+Author: Sovaria Team
+Requires-Python: >=3.11
+Requires-Dist: argon2-cffi>=23.1.0
+Requires-Dist: cryptography>=46.0.0
+Requires-Dist: email-validator>=2.2.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.29.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# Sovaria Python SDK
+
+Async Python SDK for the Sovaria gateway.
+
+## Install
+
+```bash
+pip install sovaria-sdk
+```
+
+Local workspace development:
+
+```bash
+pip install -e apps/sdk/python
+```
+
+## Supabase-Style Bootstrap (Portal Config)
+
+```python
+from sovaria import create_client
+
+client = create_client(
+    {
+        "url": "https://gateway.sovaria.in",
+        "org_id": "11111111-1111-1111-1111-111111111111",
+        "project_id": "22222222-2222-2222-2222-222222222222",
+        "env_id": "33333333-3333-3333-3333-333333333333",
+        # optional: portal-issued publishable/anon key
+        "publishable_key": "<token>",
+    }
+)
+```
+
+Or initialize directly from environment variables:
+
+```python
+from sovaria import SovariaClient
+
+client = SovariaClient.from_env()
+```
+
+Supported environment variables:
+- `SOVARIA_URL`
+- `SOVARIA_ORG_ID`
+- `SOVARIA_PROJECT_ID`
+- `SOVARIA_ENV_ID`
+- `SOVARIA_ACCESS_TOKEN` or `SOVARIA_PUBLISHABLE_KEY` or `SOVARIA_ANON_KEY`
+
+## Quick Start
+
+```python
+import asyncio
+from sovaria import SovariaClient
+
+
+async def main() -> None:
+    async with SovariaClient.from_env() as sov:
+        await sov.login("you@example.com", "password")
+        me = await sov.get_me()
+
+        # If your token includes scope claims, get_me() auto-hydrates scope.
+        # Otherwise, set scope explicitly for SQL/realtime routes:
+        # sov.set_scope(org_id="...", project_id="...", env_id="...")
+
+        health = await sov.get_engines_health()
+        print(me)
+        print(health)
+
+        # Realtime usage
+        await sov.stream_subscribe("db.table.users", "py-client-1")
+        presence = await sov.stream_presence("db.table.users")
+        print(presence)
+
+
+asyncio.run(main())
+```
+
+## Sync Quick Start
+
+```python
+from sovaria import SovariaSyncClient
+
+with SovariaSyncClient.from_env() as sov:
+    sov.login("you@example.com", "password")
+    me = sov.get_me()
+    print(me)
+```
+
+Use `SovariaSyncClient` for WSGI workers, cron jobs, and scripts where an
+explicit async event loop would add unnecessary complexity.
+
+## Coverage
+
+- Axis: auth, context, graph
+- Atlas-Doc: put/get/delete/scan plain docs
+- Atlas-Rel: SQL, table lifecycle, migrations
+- Pulse: stream, e2ee key lifecycle, websocket URL helper
+- Guard: templates, CRUD, evaluate, rollback, history
+- Echo: audit + simulation
+- Chrono: commit/timelines/snapshots/converge/variance
+- Gateway: engine health
+
+## Project Scaffold from `sovaria.config.json`
+
+You can scaffold a new client project directly from the SDK package.
+
+```python
+from sovaria import (
+    DEFAULT_CONFIG_FILENAME,
+    create_project_from_config_file,
+    write_project_config_template,
+)
+
+# 1) Write template config JSON
+write_project_config_template(DEFAULT_CONFIG_FILENAME, name="my-app")
+
+# 2) Generate project folder structure from config
+result = create_project_from_config_file(DEFAULT_CONFIG_FILENAME, target_dir=".")
+print(result.project_root)
+```
+
+Generated files include:
+
+- `<project>/sovaria.config.json`
+- `<project>/.env.example`
+- `<project>/sovaria/functions/`
+- `<project>/sovaria/migrations/`
+- `<project>/sovaria/tests/`
+
+## Raw API Escape Hatch
+
+You can call any gateway endpoint directly:
+
+```python
+await sov.request("GET", "/api/v1/system/engines/health", requires_auth=False)
+```
+
+## Functions + Storage Pass-Through
+
+```python
+# Forge deployment status
+status = await sov.fn_status("deploy-123")
+
+# Generic Vault path operations
+await sov.store_put_json("kv/app/settings", {"theme": "light"})
+settings = await sov.store_get("kv/app/settings")
+await sov.store_delete("kv/app/settings")
+```

sovaria_sdk-0.2.0/README.md

@@ -0,0 +1,148 @@
+# Sovaria Python SDK
+
+Async Python SDK for the Sovaria gateway.
+
+## Install
+
+```bash
+pip install sovaria-sdk
+```
+
+Local workspace development:
+
+```bash
+pip install -e apps/sdk/python
+```
+
+## Supabase-Style Bootstrap (Portal Config)
+
+```python
+from sovaria import create_client
+
+client = create_client(
+    {
+        "url": "https://gateway.sovaria.in",
+        "org_id": "11111111-1111-1111-1111-111111111111",
+        "project_id": "22222222-2222-2222-2222-222222222222",
+        "env_id": "33333333-3333-3333-3333-333333333333",
+        # optional: portal-issued publishable/anon key
+        "publishable_key": "<token>",
+    }
+)
+```
+
+Or initialize directly from environment variables:
+
+```python
+from sovaria import SovariaClient
+
+client = SovariaClient.from_env()
+```
+
+Supported environment variables:
+- `SOVARIA_URL`
+- `SOVARIA_ORG_ID`
+- `SOVARIA_PROJECT_ID`
+- `SOVARIA_ENV_ID`
+- `SOVARIA_ACCESS_TOKEN` or `SOVARIA_PUBLISHABLE_KEY` or `SOVARIA_ANON_KEY`
+
+## Quick Start
+
+```python
+import asyncio
+from sovaria import SovariaClient
+
+
+async def main() -> None:
+    async with SovariaClient.from_env() as sov:
+        await sov.login("you@example.com", "password")
+        me = await sov.get_me()
+
+        # If your token includes scope claims, get_me() auto-hydrates scope.
+        # Otherwise, set scope explicitly for SQL/realtime routes:
+        # sov.set_scope(org_id="...", project_id="...", env_id="...")
+
+        health = await sov.get_engines_health()
+        print(me)
+        print(health)
+
+        # Realtime usage
+        await sov.stream_subscribe("db.table.users", "py-client-1")
+        presence = await sov.stream_presence("db.table.users")
+        print(presence)
+
+
+asyncio.run(main())
+```
+
+## Sync Quick Start
+
+```python
+from sovaria import SovariaSyncClient
+
+with SovariaSyncClient.from_env() as sov:
+    sov.login("you@example.com", "password")
+    me = sov.get_me()
+    print(me)
+```
+
+Use `SovariaSyncClient` for WSGI workers, cron jobs, and scripts where an
+explicit async event loop would add unnecessary complexity.
+
+## Coverage
+
+- Axis: auth, context, graph
+- Atlas-Doc: put/get/delete/scan plain docs
+- Atlas-Rel: SQL, table lifecycle, migrations
+- Pulse: stream, e2ee key lifecycle, websocket URL helper
+- Guard: templates, CRUD, evaluate, rollback, history
+- Echo: audit + simulation
+- Chrono: commit/timelines/snapshots/converge/variance
+- Gateway: engine health
+
+## Project Scaffold from `sovaria.config.json`
+
+You can scaffold a new client project directly from the SDK package.
+
+```python
+from sovaria import (
+    DEFAULT_CONFIG_FILENAME,
+    create_project_from_config_file,
+    write_project_config_template,
+)
+
+# 1) Write template config JSON
+write_project_config_template(DEFAULT_CONFIG_FILENAME, name="my-app")
+
+# 2) Generate project folder structure from config
+result = create_project_from_config_file(DEFAULT_CONFIG_FILENAME, target_dir=".")
+print(result.project_root)
+```
+
+Generated files include:
+
+- `<project>/sovaria.config.json`
+- `<project>/.env.example`
+- `<project>/sovaria/functions/`
+- `<project>/sovaria/migrations/`
+- `<project>/sovaria/tests/`
+
+## Raw API Escape Hatch
+
+You can call any gateway endpoint directly:
+
+```python
+await sov.request("GET", "/api/v1/system/engines/health", requires_auth=False)
+```
+
+## Functions + Storage Pass-Through
+
+```python
+# Forge deployment status
+status = await sov.fn_status("deploy-123")
+
+# Generic Vault path operations
+await sov.store_put_json("kv/app/settings", {"theme": "light"})
+settings = await sov.store_get("kv/app/settings")
+await sov.store_delete("kv/app/settings")
+```

sovaria_sdk-0.2.0/examples/test_app/README.md

@@ -0,0 +1,73 @@
+Interactive Sovaria SDK Test Application
+
+Location
+- apps/sdk/python/examples/test_app
+
+Purpose
+A comprehensive interactive CLI that demonstrates all major SDK capabilities:
+- **Auth**: Register, login, logout, get user profile
+- **Graph**: Create/list nodes, create edges, get context
+- **Documents**: Put/get JSON documents
+- **SQL**: Query relational data via Atlas-Rel
+- **Streams**: Subscribe to realtime channels
+- **System**: Check engines health
+
+Features
+- Menu-driven interactive interface
+- Pretty-printed JSON responses  
+- Full response dumps for debugging
+- Session persistence (auth state maintained)
+- Error handling and recovery
+- Graceful handling of unavailable services (e.g., Atlas-Rel)
+
+Usage
+
+Run the app:
+
+```bash
+cd apps/sdk/python
+python examples/test_app/main.py
+```
+
+Or use a custom gateway URL:
+
+```bash
+SOVARIA_URL=http://my-gateway:8000 python examples/test_app/main.py
+```
+
+Interactive Menu
+- `1` — Check system health (engines status)
+- `2` — Register a new user
+- `3` — Login with credentials
+- `4` — View current user profile
+- `5` — Logout
+- `6` — Create a node (ORG, PROJECT, ENV, USER)
+- `7` — List all nodes (with optional type filter)
+- `8` — Get node details by ID
+- `9` — Create an edge (relation between two nodes)
+- `10` — Get user context on a resource
+- `11` — Write a JSON document
+- `12` — Read a JSON document
+- `13` — Execute SQL query (requires Atlas-Rel)
+- `14` — Create a relational table
+- `15` — Subscribe to a realtime channel
+- `0` — Exit
+
+Example Workflow
+
+1. Start app: `python examples/test_app/main.py`
+2. Choose `1` to check gateway health
+3. Choose `2` to register: `user@example.com`, password, and name
+4. Choose `6` to create an ORG node: name it "Acme Corp"
+5. Choose `7` to list all nodes
+6. Choose `11` to write a document: 
+   - Collection: `users`
+   - Document ID: `doc1`
+   - JSON: `{"name": "Alice", "email": "alice@acme.com"}`
+7. Choose `12` to read the document back
+
+Notes
+- The app requires the project virtualenv to be active (SDK dependencies must be installed).
+- JSON input fields expect single-line, compact JSON (no multi-line).
+- Response dumps are optional — you can skip them (press `n` when prompted).
+- If Atlas-Rel is unavailable, SQL queries will fail gracefully with a message.