jvspatial 0.0.2

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
  • Serverless Deployment (AWS Lambda)
• 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.

🚀 Serverless Ready: Deploy to AWS Lambda with zero configuration changes. Use LambdaServer and your FastAPI app is automatically wrapped with Mangum for Lambda compatibility. Includes native DynamoDB support for persistent storage in serverless environments.

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: Single Config class for all settings
• 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

☁️ Serverless Deployment (AWS Lambda)

• Zero-configuration Lambda deployment with LambdaServer
• Automatic Mangum integration for FastAPI → Lambda compatibility
• Native DynamoDB support for persistent storage in serverless environments
• Handler automatically exposed at module level for Lambda
• Works seamlessly with API Gateway
• See Lambda Example for complete deployment guide

⚙️ Unified Configuration

• Single Config class for all settings
• Environment variable support
• Type-safe configuration

🚀 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
• Serverless deployment to AWS Lambda with automatic handler setup

Installation

# Core installation
pip install jvspatial

# With serverless support (AWS Lambda + DynamoDB)
pip install jvspatial[serverless]

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
• 🚀 Serverless Lambda: examples/api/lambda_example.py - AWS Lambda deployment with DynamoDB

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_enabled=False  # Set to True to enable 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()

Serverless Deployment (AWS Lambda)

Deploy to AWS Lambda with zero configuration changes:

from jvspatial.api import endpoint
from jvspatial.api.lambda_server import LambdaServer
from jvspatial.core import Node

# Use LambdaServer for Lambda deployments - handler is automatically created and exposed
# DynamoDB is the default database (can be overridden)
server = LambdaServer(
    title="Lambda API",
    dynamodb_table_name="myapp",
    dynamodb_region="us-east-1",
)

class Product(Node):
    name: str = ""
    price: float = 0.0

@endpoint("/products", methods=["GET"])
async def list_products():
    products = await Product.find({})
    import asyncio
    products_list = await asyncio.gather(*[p.export() for p in products])
    return {"products": products_list}

# Handler is automatically available at module level for Lambda
# No manual assignment needed! AWS Lambda will call: lambda_example.handler

Deployment Steps:

1. Install: pip install jvspatial[serverless]
2. Package your code and dependencies
3. Set Lambda handler to: your_module.handler
4. Configure API Gateway trigger
5. Deploy!

See the complete Lambda example for full deployment guide.

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

Server Configuration

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_auth_enabled=True,
    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 Implementation Standards - Standard patterns and best practices

API Development

• REST API Guide - API design patterns
• Server API Guide - Server configuration and serverless deployment
• Authentication Guide - Authentication patterns
• Entity Reference - Node, Edge, Walker classes
• Lambda Deployment Example - Complete AWS Lambda setup with DynamoDB

Advanced Topics

• 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.