Intents

Intents are the core building blocks of Intend. They describe what you want a function to do, leaving the implementation details to the AI compiler.

Anatomy of an Intent

An .intent file can contain one or more intent definitions. It uses a C-like syntax.

File: types.ts

export interface CartItem {
  name: string;
  price: number;
  quantity: number;
}

File: shop.intent

import { CartItem } from "./types"

// 1. The Entry Point (Runnable Script)
// This intent takes no arguments, so it will run automatically when you build!
export entry intent RunDemo() -> void {
    step "Create a list of 3 mock cart items (Laptop, Mouse, Keyboard)" => const items
    step "Calculate the total price for these items" => const total
    
    // Intents can call other intents!
    CalculateTotal(items) => const finalPrice
    
    step "Log the final price to the console"
}

// 2. The Business Logic
export intent CalculateTotal(items: CartItem[]) -> number {
    step "Sum up the price * quantity for all items" => const sum
    step "Apply a 10% discount if the sum is over $100" => const total
    
    return total
}

Syntax Breakdown

export entry intent

• export: Makes the intent valid for external checks (logic review).
• entry: Tells the compiler to generate a top-level exported function in the output TypeScript file.
• IntentName(params): Defines the function signature including parameter names and types.
• -> ReturnType: Specifies the return type of the function.

Steps

Steps are written in plain English. They guide the AI on what logic to generate.

step "Validate the email address format"

Variable Binding

You can bind the result of a step to a variable using => const varName.

step "Fetch user from database" => const user
step "Log the user's name: ${user.name}"

Hybrid Orchestration

Intend isn't just about replacing code with AI. It's about orchestrating them together.

Pure AI can be unpredictable. Pure code is rigid. Intend allows you to mix them seamlessly. This feature is called Direct Function Calls.

How it works

You can invoke any imported function or another Intent directly within your step flow. These calls are deterministic—the compiler emits a standard function call in TypeScript, bypassing the AI interpretation for that specific line.

Use Cases

1. Reliability: When you have a mission-critical function (like charging a credit card), you don't want the AI to "interpret" how to do it. You want it to call chargeCard().
2. Logging & Audit: Ensure specific audit logs are written exactly when you want them.
3. Reuse: Leverage existing TypeScript utilities or libraries.

Example: Processing a Refund

In this example, we use AI to "analyze" the sentiment (fuzzy logic) but use a hard-coded function to "process the refund" (strict logic).

import { ProcessRefund, LogRefund } from "./payment_system";

export intent HandleComplaint(feedback: string, orderId: string) -> void {
    // 🧠 AI Step: Fuzzy logic to understand the user
    step "Analyze the feedback sentiment. If it's very angry, set severity to 'high', else 'low'" => const severity
    
    // 🔀 Direct Call: Deterministic execution
    // variable 'severity' from AI step is passed to code!
    ProcessRefund(orderId, severity) => const refundParams

    step "Generate a polite apology email based on severity" => const emailBody

    // 🔀 Direct Call: Logging
    LogRefund(orderId, "Refund Processed via AI")
}

This ensures that while the understanding is robust and flexible, the action is safe and predictable.

step "Calculate totals" => const total }

## Global Context
You can set file-level rules or context using the `context` keyword at the very top of your `.intend` file. This is useful for "priming" the AI with domain-specific knowledge that applies to every intent in the file.

```typescript
context "This module handles Order Processing. All currency values must be handled as integers (cents)."

import { Order } from "./types";

export intent CreateOrder(cart: Cart) -> Order {
   // The AI now knows about the currency rule automatically 🪄
   step "Calculate totals" => const total
}

More Keywords

Intend also supports advanced keywords for safety and validation:

• invariant: Define constraints that must be true.
• ensure: Guarantee output states.

For a complete list of keywords and detailed usage, see the Syntax Guide.