Skip to main content

Installation

Install the Taruvi SDK in your development environment with your preferred package manager.

Choose Your Language​

Python SDK​

Requirements​

  • Python: 3.10 or higher
  • Operating Systems: Linux, macOS, Windows

Installation​

Choose your preferred package manager:

pip install taruvi

Verify Installation​

import taruvi
print(f"Taruvi SDK version: {taruvi.__version__}")

Initializing the Client​

from taruvi import Client

# Create client — api_url and app_slug are required
client = Client(
    api_url="https://api.taruvi.cloud",
    app_slug="my-app"
)

# Check client is ready
print(f"Client initialized for app: {client.config.app_slug}")
print(f"Authenticated: {client.is_authenticated}")  # False until auth

Configuration Options​

The Python SDK supports multiple configuration methods:

from taruvi import Client

client = Client(
    api_url="https://api.taruvi.cloud",
    app_slug="my-app",
    timeout=60,
    max_retries=5
)

# Then authenticate separately
auth_client = client.auth.signInWithToken(token="your-jwt", token_type="jwt")

2. Environment Variables​

The SDK uses pydantic-settings and automatically reads TARUVI_-prefixed environment variables. Create a .env file in your project root:

# .env file
TARUVI_API_URL=https://api.taruvi.cloud
TARUVI_APP_SLUG=my-app
TARUVI_TIMEOUT=60
TARUVI_MAX_RETRIES=5

# Optional: Authentication credentials
TARUVI_JWT=your-jwt-token
TARUVI_API_KEY=your-api-key
TARUVI_SESSION_TOKEN=your-session-token
from taruvi import Client

# Client reads TARUVI_* env vars automatically via pydantic-settings
# api_url and app_slug are still required positional arguments
client = Client(
    api_url="https://api.taruvi.cloud",
    app_slug="my-app"
)
Configuration Precedence
  1. Explicit parameters passed to Client() (highest priority)
  2. Environment variables (TARUVI_*)
  3. .env file values
  4. Default values (lowest priority)

3. Runtime Detection (Inside Taruvi Functions)​

When running inside a Taruvi function, the SDK auto-detects the runtime environment and merges configuration from environment variables set by the platform:

from taruvi import Client

# Inside a Taruvi function, TARUVI_API_URL and TARUVI_APP_SLUG
# are set automatically by the runtime environment
client = Client(
    api_url="http://localhost:8000",  # Or use env var
    app_slug="my-app"
)

# Authentication is automatically inherited from the function runtime
# when TARUVI_JWT or TARUVI_API_KEY env vars are set
users = client.database.from_("users").execute()
Runtime Auto-Configuration

When TARUVI_FUNCTION_RUNTIME=true is set (automatically by the platform), the SDK loads function context including function_id, execution_id, and tenant from environment variables.

Async Mode​

For async/await support:

from taruvi import Client
import asyncio

async def main():
    # Create async client
    client = Client(
        api_url="https://api.taruvi.cloud",
        app_slug="my-app",
        mode='async'
    )

    # Authenticate
    auth_client = client.auth.signInWithToken(
        token="your-jwt-token",
        token_type="jwt"
    )

    # Use async operations
    result = await auth_client.database.from_("users").execute()
    users = result["data"]

    # Close connection
    await auth_client.close()

asyncio.run(main())
Sync vs Async
  • mode='sync' (default): Uses native httpx.Client — blocking, thread-safe, works everywhere including Jupyter notebooks
  • mode='async': Uses httpx.AsyncClient — for async frameworks like FastAPI, aiohttp
  • If mode is omitted, auto-detects based on whether an event loop is running

IDE Setup​

Visual Studio Code​

For the best development experience with VS Code:

Python:

  1. Install the Python extension
  2. Enable type checking in settings.json:
{
    "python.analysis.typeCheckingMode": "basic",
    "python.analysis.autoImportCompletions": true
}

JavaScript/TypeScript:

  1. Install the TypeScript extension (built-in)
  2. Enable import suggestions:
{
    "typescript.suggest.autoImports": true,
    "javascript.suggest.autoImports": true
}

PyCharm / WebStorm​

PyCharm (Python):

  • Type hints are automatically recognized
  • Enable "Enable type annotations" in Settings → Editor → General → Code Completion

WebStorm (JavaScript):

  • TypeScript support is built-in
  • Enable "TypeScript" language service

Troubleshooting​

Python Issues​

Import Error: "No module named 'taruvi'"​

Solution: Ensure you're using the correct Python environment:

# Check Python version
python --version  # Should be 3.10+

# Reinstall in current environment
pip install --force-reinstall taruvi

Type Hint Errors in IDE​

Solution: Update your IDE's Python language server or install type stub packages:

pip install types-requests

SSL Certificate Errors​

Solution: Update your certificates or specify a custom certificate:

import os
os.environ['REQUESTS_CA_BUNDLE'] = '/path/to/cacert.pem'

JavaScript Issues​

Module Resolution Errors​

Solution: Ensure your package.json has the correct module type:

{
    "type": "module"
}

Or use CommonJS require:

const { Client } = require('@taruvi/sdk')

TypeScript Errors​

Solution: Ensure TypeScript is configured correctly in tsconfig.json:

{
    "compilerOptions": {
        "moduleResolution": "node",
        "esModuleInterop": true,
        "strict": true
    }
}

Browser CORS Errors​

Solution: CORS must be configured on the Taruvi server. Contact your administrator or check CORS documentation.

Upgrading​

Check Current Version​

pip show taruvi

Upgrade to Latest Version​

pip install --upgrade taruvi

Breaking Changes​

Check the CHANGELOG for breaking changes before upgrading major versions.

Next Steps​

Now that you have the SDK installed: