---
audience: engineers
summary: 'The declarations that appear at module scope: @core, @flow, @transformer,
  @evaluator, @pipeline, @test, type aliases, imports.'
title: Top-level constructs
path: reference/language/top-level-constructs
status: published
---

### 4.1 `@core` — Core Declaration

The root container. One per project entry point.

```scaicore
@core CoreName {
    version = "1.0.0"
    description = "What this Core does"

    // Instance mode: :stateless (default), :entity(key), or :singleton
    instance = :entity(key = "customer_id") {
        idle_timeout = 30m
        max_concurrent = 1
        max_active_instances = 10000
        overflow = :deactivate_lru
    }

    @plugins { ... }
    @llm { ... }
    @memory { ... }        // Per-instance (exclusive) memory
    @reference { ... }     // Read-only data, immutable at runtime
    @config { ... }
    @constraints { ... }
    @conversation_policy { ... }

    identity = {
        name = "Alex"
        personality = """
            Friendly, professional, solution-oriented.
        """
        languages = ["nl", "en", "de"]
    }

    @triggers {
        @webhook incoming_message {
            flow = handle_message
            method = "POST"
            path = "/api/v1/support/message"
        }
        @schedule daily_digest {
            flow = generate_digest
            cron = "0 9 * * *"
            timezone = "Europe/Amsterdam"
        }
        @api submit_ticket {
            flow = handle_ticket
        }
    }

    // Event subscriptions: react to events from other Cores
    @on invoice_processed from core://invoice-processor {
        flow = record_transaction
    }
}
```

**Instance modes:**

| Mode | Declaration | Memory | Routing |
|------|------------|--------|---------|
| Stateless | `instance = :stateless` (default) | Per-Core (one partition) | Any worker |
| Entity | `instance = :entity(key = "field")` | Per-entity (exclusive) | By key extraction |
| Singleton | `instance = :singleton` | Per-instance (one exists) | Always to the one |

### 4.2 `@flow` — Behavioral Unit

The primary unit of execution. In `:entity` Cores, entry-point flows
must include the entity key parameter. Internal flows can omit it.

```scaicore
// Entry-point flow (reachable from triggers)
// Must include entity key if Core is :entity(key = "customer_id")
@flow handle_message(customer_id: string, message: string): Response {
    // ... blocks ...
}

// Internal flow — only called via @call from other flows
// Does not need entity key parameter
@internal
@flow validate_input(data: any): ValidationResult {
    // ... blocks ...
}
```

### 4.3 `@transformer` — Pure Content Transformation

Takes input, produces output. No side effects. Can bind to a specific LLM.

```scaicore
@transformer Draft(brief: Brief): Content {
    llm = drafter

    result = @flexible {
        goal = "create initial draft from brief"
        input = brief
        context = memory.style_guides.get(brief.brand)
        output = { body: string, metadata: Metadata }
        guidance = """
            Write freely. Focus on the core message.
            Match the tone specified in the brief.
        """
    }

    return Content.new({
        body = result.body,
        metadata = result.metadata,
        format = brief.output_format,
        version = 1
    })
}
```

### 4.4 `@evaluator` — Assessment Without Mutation

Returns a score or assessment. Never transforms the input.

```scaicore
@evaluator AssessQuality(content: Content, standards: QualityStandards): QualityScore {
    @parallel {
        llm_score = @flexible {
            goal = "assess content quality"
            llm = critic
            input = { content: content, criteria: standards.criteria }
            output = {
                clarity: float,
                engagement: float,
                originality: float,
                issues: array[Issue]
            }
        }

        plagiarism_result = plagiarism.check(content.body)
        seo_result = seo_analyzer.analyze(content)
    }

    @rigid {
        score = QualityScore.compute({
            llm = llm_score,
            plagiarism = plagiarism_result,
            seo = seo_result,
            weights = standards.weights
        })
    }

    return score
}
```

### 4.5 `@pipeline` — Named Composition

Chains transformers and evaluators using pipeline operators.

```scaicore
@pipeline BlogPostPipeline = {
    Draft
    |> EnrichMetadata
    |~> RefineLoop(BlogStandards), until = quality_passes, max = 3
    |> Polish
    |> FinalQualityGate(BlogStandards)
}

@pipeline SocialMediaPipeline = {
    Draft
    |> RefineLoop(SocialStandards), until = quality_passes, max = 2
    |*> [
        FormatForPlatform("twitter"),
        FormatForPlatform("linkedin"),
        FormatForPlatform("instagram")
    ], merge = PackageMultiPlatform
}
```

### 4.6 `@types` — Type Definitions

```scaicore
@types {
    type Invoice = { ... }
    type LineItem = { ... }
    type InvoiceStatus = enum[draft, pending, approved, rejected, paid]
    type Amount = "small" | "medium" | "large"
}
```

### 4.7 `@plugin_interface` — External Service Contract

```scaicore
@plugin_interface CRM {
    version = "1.0"

    identify(by: string, value: string): Customer
        @errors [NotFound, RateLimited]
        @latency "fast"

    create_ticket(customer_id: string, subject: string, body: string): Ticket
        @errors [ValidationError, RateLimited]
        @latency "medium"
}
```

### 4.8 `@core_interface` — Public Core Contract

Declares what other Cores can call and what events this Core emits.

```scaicore
@core_interface BillingSpecialist {
    version = "2.0"

    // Callable flows
    pub analyze_dispute(
        customer_id: string,
        dispute_description: string,
        invoices: array[string]?
    ): DisputeAnalysis

    // Event types this Core emits (for typed subscriptions)
    event invoice_processed {
        invoice_id: string
        vendor: string
        total: money
        processed_at: datetime
    }

    event invoice_rejected {
        invoice_id: string
        reason: string
        rejected_at: datetime
    }
}
```

### 4.9 `@test` — Test Flows

```scaicore
@test flow test_invoice_extraction {
    description = "Verifies invoice data extraction from OCR text"

    @given {
        ocr_text = "Invoice #INV-2026-0042\nDate: January 15, 2026\nTotal: $500.00"

        @mock plugin:ocr {
            extract_text = { text: ocr_text, confidence: 0.94 }
        }

        @mock llm {
            response = {
                invoice_number: "INV-2026-0042",
                date: "2026-01-15",
                total: 500.00
            }
        }
    }

    @when {
        result = @call extract_invoice(ocr_text)
    }

    @then {
        assert result.invoice_number == "INV-2026-0042"
        assert result.total == 500.00
    }
}
```

---