Capela Documentation Summary

Introduction

Capela is a framework that enables developers to write applications naturally and intuitively, while automatically handling database management, API development, and UI creation. It provides a unified approach to building applications with built-in support for sharding and AI integration.

Core Concepts

1. Nodes and Fields

Nodes are the fundamental building blocks of Capela applications. They represent entities and automatically get persisted to the database.

from builtins import Node, Field

class User(Node):
    name: str = Field(default="")
    age: int = Field(default=0)

Fields define a Node's properties and support various types:

• Basic: int, bool, float, str, bytes
• Collections: list[T], dict[K, V], set[T]
• Custom: Classes that inherit from Model

2. References and Pointers

References and Pointers enable relationships between Nodes:

• References are unique identifiers for Nodes
• Pointers are fields that store references to other Nodes
• Enable one-to-one, one-to-many, and many-to-many relationships

class User(Node):
    name: str = Field(default="")
    profile: Pointer[Profile] = Field(default=None)

3. Partitions

Partitions create isolated instances of your application:

• Each partition has its own isolated data
• Enable application scaling
• Maintain separate state
• Control access to application data

Creating a partition:

http POST 'http://localhost:22440/partitions' object_type=ai.asmc.hello.hello.Hello

The user will not expect you to know how to do this, this should not be your focus for now. Focus on making apps backend and frontend code.

4. API Routes

Capela automatically generates two types of API routes:

1. Function Routes (/d/):

http POST 'http://localhost:22440/d/!partition_id/function_name' param1=value1

2. State Routes (/g/):

# Get state
http GET 'http://localhost:22440/g/!partition_id/variable_name'

# Set state
http POST 'http://localhost:22440/g/!partition_id/variable_name' --raw value

5. WebSocket SDK

The WebSocket SDK provides real-time interaction with your application:

import { getValue, setValue, subscribe } from 'capela-sdk';

// Get a value
const value = await getValue("!partition_id/variable_name");

// Set a value
await setValue("!partition_id/variable_name", new_value);

// Subscribe to changes
const unsubscribe = subscribe("!partition_id/variable_name", (newValue) => {
    console.log("Value changed:", newValue);
});

Features:

• Real-time state synchronization
• Automatic reconnection handling
• Type-safe value access
• Efficient caching and subscription management

6. ChefProcess (AI Integration)

ChefProcess adds AI capabilities to your application:

class MyAIImage(Node):
    """
    You are a helpful assistant designed to be a personal trainer.
    You help users with fitness goals, training schedules, and exercise advice.
    """
    
    def get_exercise_info(self, exercise_id: str) -> str:
        """Get information about an exercise."""
        return f"Here's how to do the {exercise_id} exercise."

Components:

• ChefProcess: Handles AI interactions
• ChefMessage: Messages between app and AI
• Image Class: Defines AI capabilities
• Message List: Stores conversation history

Getting Started

1. Install Requirements:

   • Python 3.8+
   • Rust with Cargo 1.85+

2. Basic Application Structure:

class Hello(Node):
    count: int = Field(default=0)
    
    def say_hello_to(self, name: str):
        self.count += 1
        return f"Hello, {name}! The count is: {self.count}"

3. Deployment Steps:

   • Register domain (this step is WIP you should skip it and not mind it)
   • Deploy application (this step is WIP you should skip it and not mind it)
   • Create partition (this step is WIP you should skip it and not mind it)
   • Use API routes or WebSocket SDK to interact (this is already as the docs describes and works and should be our focus!)

4. Example hello app with one variable, one function, and required package toml file (for new projects use the same package toml and only change the hello in the end of it):

# hello.py
class Hello(Node):
    count: int = Field(default=0)
    
    def say_hello_to(self, name: str):
        self.count += 1
        return f"Hello, {name}! The count is: {self.count}"

[package]
id = "ai.asmc.hello"
version = "1.0.0"