jvspatial 0.0.6

An asynchronous object-spatial Python library for persistence and business logic application layers.

jvspatial

An async-first Python library for building graph-based spatial applications with FastAPI integration. Provides entity-centric database operations with automatic context management.

Table of Contents

• Overview
• Key Features
• Installation
• Quick Start
  • Basic Example
• Core Concepts
• Configuration
• Documentation
• Contributing
• License

Overview

jvspatial is an async-first Python library for building graph-based spatial applications with FastAPI integration. It provides entity-centric database operations with automatic context management.

Inspired by Jaseci's object-spatial paradigm and leveraging Python's async capabilities, jvspatial empowers developers to model complex relationships, traverse object graphs, and implement agent-based architectures that scale with modern cloud-native concurrency requirements.

Key Design Principles:

• Hierarchy: Object → Node → Edge/Walker inheritance
• Entity-Centric: Direct database operations via entity methods
• Unified Decorators: @attribute for entity attributes, @endpoint for API endpoints
• Automatic Context: Server automatically provides database context to entities
• Essential CRUD: Core database operations with pagination support
• Unified Configuration: Pydantic ServerConfig merged at Server startup (constructor kwargs / config dict override allowlisted JVSPATIAL_* env, which override library defaults)
• Async-First: Built for modern Python async/await patterns

Key Features

🎯 Inheritance Hierarchy

• Object: Base class for all entities
• Node: Graph nodes with spatial data (inherits from Object)
• Edge: Relationships between nodes (inherits from Object)
• Walker: Graph traversal and pathfinding (inherits from Object)
• Root: Singleton root node (inherits from Node)

🎨 Unified Decorator System

• @attribute - Define entity attributes with protection, transient flags, and validation
• @endpoint - Unified endpoint decorator for both functions and Walker classes
• Automatic parameter and response schema generation

🗄️ Entity-Centric Database Operations

• Entity methods: Entity.get(), Entity.find(), Entity.create(), entity.save(), entity.delete()
• Automatic context management
• Support for JSON, SQLite, MongoDB, and DynamoDB backends
• Multi-database support with prime database for core persistence
• Custom database registration for extensibility
• Pagination with ObjectPager

⚙️ Unified Configuration

• Canonical ServerConfig (Pydantic) for all server settings
• Allowlisted JVSPATIAL_* env vars merged before explicit Server(...) / config= overrides
• Unknown or removed JVSPATIAL_* keys are rejected (see docs/md/environment-configuration.md)

🚀 FastAPI Integration

• Built-in FastAPI server with automatic OpenAPI documentation
• Automatic endpoint registration from decorators
• Authentication and authorization with automatic endpoint registration when enabled
• Response schema definitions with examples
• Entity-centric CRUD operations

⚡ Performance Mixins

• DeferredSaveMixin: Batch multiple save() calls into a single database write
• Configurable via JVSPATIAL_ENABLE_DEFERRED_SAVES; disabled automatically in serverless mode (deferred_saves_globally_allowed())
• Ideal for entities with rapid, sequential updates

Installation

# Core installation
pip install jvspatial

Quick Start

Standard Examples: For production-ready API implementations, see:

• Authenticated API: examples/api/authenticated_endpoints_example.py - Complete CRUD with authentication
• Unauthenticated API: examples/api/unauthenticated_endpoints_example.py - Public read-only API

Basic Example

from jvspatial.api import Server, endpoint
from jvspatial.core import Node

# Create server (entity-centric operations available automatically)
server = Server(
    title="My API",
    db_type="json",
    db_path="./jvdb",
    auth=dict(auth_enabled=False)  # Set auth_enabled=True for authentication
)

# Define entity
class User(Node):
    name: str = ""
    email: str = ""

# Create endpoint
@endpoint("/users/{user_id}", methods=["GET"])
async def get_user(user_id: str):
    user = await User.get(user_id)
    if not user:
        from fastapi import HTTPException
        raise HTTPException(status_code=404, detail="User not found")
    return {"user": await user.export()}

if __name__ == "__main__":
    server.run()

Core Concepts

Entity Definition and Attributes

from jvspatial.core import Node
from jvspatial.core.annotations import attribute

class User(Node):
    name: str = ""
    email: str = ""
    cache: dict = attribute(transient=True, default_factory=dict)

Unified Endpoint Decorator

The @endpoint decorator works with both functions and Walker classes:

from jvspatial.api import Server, endpoint
from jvspatial.core import Node

server = Server(title="My API", db_type="json", db_path="./jvdb")

# Function endpoint
@endpoint("/api/users", methods=["GET"])
async def list_users(page: int = 1, per_page: int = 10):
    from jvspatial.core.pager import ObjectPager
    pager = ObjectPager(User, page_size=per_page)
    users = await pager.get_page(page=page)
    import asyncio
    users_list = await asyncio.gather(*[user.export() for user in users])
    return {"users": users_list}

# Authenticated endpoint
@endpoint("/api/admin", methods=["GET"], auth=True, roles=["admin"])
async def admin_panel():
    return {"admin": "dashboard"}

# Endpoint with response schema
from jvspatial.api.endpoints.response import ResponseField, success_response

@endpoint(
    "/api/users",
    methods=["GET"],
    response=success_response(
        data={
            "users": ResponseField(List[Dict], "List of users"),
            "total": ResponseField(int, "Total count")
        }
    )
)
async def get_users():
    return {"users": [], "total": 0}

Entity-Centric Database Operations

from jvspatial.core import Node

class User(Node):
    name: str = ""
    email: str = ""

# Entity-centric operations (no context needed - server provides it automatically)
user = await User.create(name="John", email="[e-mail]")
users = await User.find({"context.name": "John"})  # Use context. prefix for fields
user = await User.get(user_id)  # Returns None if not found
if user:
    await user.save()
    await user.delete()

# Efficient counting
total_users = await User.count()  # Count all users
active_users = await User.count({"context.active": True})  # Count filtered users using query dict
active_users = await User.count(active=True)  # Count filtered users using keyword arguments

Configuration

Serverless Mode

Set SERVERLESS_MODE=true to force serverless-safe behavior (strict synchronous request lifecycle, no fire-and-forget background task assumptions). When unset, jvspatial auto-detects AWS Lambda via runtime environment variables. Use is_serverless_mode() from jvspatial.runtime.serverless to check mode at runtime.

For deferred work across invocations, use dispatch_deferred_task() from jvspatial.serverless. On AWS, Lambda async invoke and optional EventBridge deliver JSON to your app; with the Lambda Web Adapter, Server applies best-effort AWS_LWA_PASS_THROUGH_PATH / AWS_LWA_INVOKE_MODE defaults when LWA is detected (see docs/md/serverless-mode.md); set them in IaC when the extension must read them before Python starts. Register task handlers with register_deferred_invoke_handler() in jvspatial.serverless.deferred_invoke.

Server configuration

Merge order when constructing Server is: ServerConfig defaults → allowlisted JVSPATIAL_* environment → config= dict or keyword arguments (later wins). Import ServerConfig from jvspatial.api when you need the schema outside Server.

from jvspatial.api import Server

# Basic server
server = Server(
    title="My API",
    description="API description",
    version="1.0.0",
    db_type="json",
    db_path="./jvdb"
)

# Server with authentication
server = Server(
    title="Secure API",
    auth_enabled=True,  # Automatically registers /auth/register, /auth/login, /auth/logout
    jwt_secret="your-secret-key",
    jwt_expire_minutes=60,
    db_type="json",
    db_path="./jvdb"
)

# Server without authentication (public API)
server = Server(
    title="Public API",
    auth_enabled=False,  # NO authentication endpoints registered
    db_type="json",
    db_path="./jvdb_public"
)

Authentication Behavior

• auth_enabled=True: Server automatically registers authentication endpoints (/auth/register, /auth/login, /auth/logout)
• auth_enabled=False: Authentication endpoints are NOT registered (public API)

Documentation

Getting Started

• Quick Start Guide - Get started in 5 minutes
• Examples - Standard implementation examples
  • Authenticated API Example - Complete CRUD with authentication
  • Unauthenticated API Example - Public read-only API

API Development

• REST API Guide - API design patterns
• Server API Guide - Server configuration
• Authentication Guide - Authentication patterns
• Entity Reference - Node, Edge, Walker classes

Advanced Topics

• Serverless mode - Deferred tasks, Lambda Web Adapter, and LWA env defaults
• Production Deployment - Production checklist and security
• API Architecture - System architecture
• Graph Context Guide - Context management and multi-database support
• Custom Database Guide - Implementing custom database backends
• Graph Visualization - Export graphs in DOT/Mermaid formats
• Pagination - ObjectPager usage

Contributors

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.