System Context

Understanding where the Ainalyn SDK fits in the overall system architecture.

Application Architecture

SDK as a Compiler

The most important concept to understand: the SDK is compiler-first with an optional runtime wrapper for ATOMIC handlers. Platform Core still owns execution, state, and billing.

Key Boundaries

What the SDK Does

Responsibility	Description
Define	Provides builders to define Agent structure
Validate	Checks schema, review gates, and static analysis
Export	Produces platform-compatible YAML format
Runtime wrapper (optional)	Wraps ATOMIC handlers to follow the Core invocation protocol
Compile	Complete workflow: validate -> serialize -> output

What the SDK Does NOT Do

NOT Responsibility	Why
Decide execution	Platform Core schedules and authorizes runs
Call LLMs	Platform Core manages LLM interactions
Manage state	Platform Core owns runtime state
Handle I/O	Platform Core manages external integrations

The Compilation Analogy

Think of Ainalyn SDK like a programming language compiler:

Python Builders -> SDK -> Agent Definition (YAML)
                        Platform Core executes

Data Flow Overview

Developer -> SDK -> Platform Core

Build with builders
Validate (schema + gates + static)
Export YAML
Submit to Platform Core
Core executes and governs

Why This Separation?

Benefits of Compiler Pattern

Offline Validation
- Catch errors before deployment
- No network calls needed for validation
- Fast feedback loop for developers
Platform Independence
- SDK produces a standard format (YAML)
- Platform can evolve independently
- Multiple platforms could consume the same format
Clear Responsibility
- SDK: definition correctness
- Platform: execution correctness
- No confusion about where bugs originate
Testability
- Test definitions without running agents
- Mock-free unit tests for SDK
- Integration tests only at platform level

What Gets Compiled

The SDK compiles your Python builder calls into an Agent Definition:

Input (Python):

from ainalyn import AgentBuilder, WorkflowBuilder, NodeBuilder
 
agent = (
    AgentBuilder("customer-support")
    .version("1.0.0")
    .description("Handles customer inquiries")
    .add_workflow(
        WorkflowBuilder("handle-inquiry")
        .add_node(
            NodeBuilder("classify")
            .description("Classify request")
            .uses_prompt("classify-prompt")
            .next_nodes("respond")
            .build()
        )
        .add_node(
            NodeBuilder("respond")
            .description("Respond to request")
            .uses_prompt("respond-prompt")
            .build()
        )
        .entry_node("classify")
        .build()
    )
    .build()
)

Output (YAML):

name: customer-support
version: 1.0.0
description: Handles customer inquiries
workflows:
  - name: handle-inquiry
    entry_node: classify
    nodes:
      - name: classify
        description: Classify request
        type: prompt
        reference: classify-prompt
        next_nodes:
          - respond
      - name: respond
        description: Respond to request
        type: prompt
        reference: respond-prompt

Hexagonal Architecture - Internal SDK architecture
Compilation Flow - Detailed compilation process

Architecture & Code Guide Compilation Flow