Skip to main content

Core Concepts

Capela's core concepts are simple but powerful. Here's what you need to know to build effective applications.

Nodes​

Nodes are the building blocks of your application. Each Node represents an entity and automatically gets persisted to the database.

from builtins import Node, Field

class User(Node):
    name: str = Field(default="")
    age: int = Field(default=0)
    
    def activate(self):
        this.is_active = True
        return this.is_active

Fields​

Fields define a Node's properties. They're strongly typed and support default values.

class Task(Node):
    title: str = Field(default="")
    done: bool = Field(default=False)
    tags: list[str] = Field(default_factory=list)
    preferences: dict[str, bool] = Field(default_factory=dict)

Supported types:

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

References and Pointers​

Nodes can reference each other using references and pointers:

from builtins import Node, Field, Pointer, select

class User(Node):
    name: str = Field(default="")
    profile: Pointer[Profile] = Field(default=None)
    
    def get_reference(self):
        return this.make_reference()
    
    def get_user_by_reference(self, reference):
        return select(reference)

References and pointers enable:

  • One-to-One relationships
  • One-to-Many relationships
  • Many-to-Many relationships
  • Efficient data access and traversal

ChefProcess​

ChefProcess adds AI capabilities to your application. It consists of:

  • ChefProcess: Handles AI interactions
  • ChefMessage: Messages between your app and the AI
  • Image Class: Defines the AI's capabilities and behavior
  • Message List: Stores conversation history
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."

Partitions​

Partitions create isolated instances of your application:

# Create a partition
http POST 'http://localhost:22440/partitions' object_type=ai.asmc.hello.hello.Hello

Partitions provide:

  • Data isolation
  • Application scaling
  • State management
  • Access control

API Routes​

Capela generates API routes automatically:

  • Call functions with /d/:

    http POST 'http://localhost:22440/d/!partition_id/say_hello_to' name="Alice"

  • Get state with /g/:

    # Fetch a value
    http GET 'http://localhost:22440/g/!partition_id/count'

    # Set a dictionary value
    http POST 'http://localhost:22440/g/!partition_id/users/"Alice"' --raw '{"name": "Alice", "age": 30}'

    # Set an array value
    http POST 'http://localhost:22440/g/!partition_id/users/0' --raw '{"name": "Alice", "age": 30}'

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);
});

// Later, when you want to stop listening:
unsubscribe();

Features:

  • Real-time state synchronization
  • Automatic reconnection handling
  • Type-safe value access
  • Efficient caching and subscription management
  • Children access and nested value support
  • Robust error handling

Explore Capela Core Concepts​