> ## Documentation Index
> Fetch the complete documentation index at: https://docs.astrakairo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Kairo Standard Library: Core, Pulse Runtime, and Astra

> Explore the three-layer Kairo standard library: Core prelude types, Pulse runtime modules, and optional Astra first-party packages.

Kairo's standard library is organized into three distinct layers, each designed for a specific scope of availability and use. The **Kairo Core** prelude is always present — no imports needed for everyday types. **Pulse Runtime Services** extend the runtime with I/O, process control, and environment access for application packages. **Astra First-Party Packages** are optional, explicitly declared dependencies that add capabilities like JSON, HTTP, file system access, and more. Understanding which layer provides what helps you write clean, intentional code without pulling in more than you need.

| Layer                         | Namespace | Availability                                  |
| ----------------------------- | --------- | --------------------------------------------- |
| Kairo Core                    | `Kairo.*` | Automatic with every Kairo toolchain          |
| Pulse Runtime Libraries       | `Pulse.*` | Automatic with Pulse for application packages |
| First-Party Optional Packages | `Astra.*` | Explicit manifest dependency required         |

***

## Kairo Core

Kairo Core is always available — you never need an import statement to use its prelude types. These are the foundational primitives and collections that every Kairo program can rely on, regardless of package type or target environment.

### Prelude types (no import required)

The following types are in scope automatically in every Kairo file:

* **`Bool`** — boolean true/false values
* **`Text`** — the primary text type in Kairo (see note below)
* **`Int32`**, **`Int64`** — fixed-width integer types
* **`Decimal`** — the default type for fractional literals
* **`Float64`** — IEEE 754 double-precision float; requires explicit typing
* **`Date`**, **`Time`**, **`DateTime`**, **`Instant`**, **`Duration`** — comprehensive date and time primitives
* **`List<T>`**, **`Set<T>`**, **`Map<K, V>`** — immutable collection types
* **`MutableList<T>`**, **`MutableSet<T>`**, **`MutableMap<K, V>`** — mutable collection variants
* **`Result<T, E>`** — typed error handling

Core also includes core math operations and parsing/formatting utilities for all of the above types.

<Note>
  **`Text`, not `String`** — Kairo's primary text type is `Text`. There is no `String` type in Core. If you see `String` in Kairo code, it does not refer to a built-in.

  **`Decimal`, not `Float64` by default** — Fractional literals such as `3.14` are typed as `Decimal` unless you explicitly annotate them as `Float64`. Use `Float64` only when you have a specific reason to prefer binary floating-point arithmetic.
</Note>

### What is NOT in Kairo Core

Core is intentionally minimal. The following capabilities are **not** provided by Core and must be sourced from Pulse or Astra packages:

* JSON and XML processing
* File system access
* HTTP client or server
* Database access
* Application configuration
* Cryptography
* Monetary values (`Money` is **not** a core primitive)
* Console/stdout output

***

## Pulse Runtime Services

Pulse Runtime Services are available in all **application packages** — they ship alongside the Pulse runtime and do not require a manifest dependency. However, each module must be explicitly imported before use. Pulse is not a keyword or global; you must bring each module into scope with an `import` statement.

### Available Pulse modules

| Module              | Purpose                            |
| ------------------- | ---------------------------------- |
| `Pulse.Console`     | stdout and stderr output           |
| `Pulse.Environment` | environment variable access        |
| `Pulse.Process`     | process lifecycle and control      |
| `Pulse.Runtime`     | runtime metadata and introspection |
| `Pulse.Clock`       | current time and clock access      |

### Pulse.Console

`Pulse.Console` is your gateway to standard output and standard error. Import it at the top of any file that needs to write to the console.

**`Pulse.Console.out`** — writes to stdout:

* `.writeLine(value)` — writes the value followed by a newline
* `.write(value)` — writes the value without a trailing newline

**`Pulse.Console.error`** — writes to stderr:

* `.writeLine(value)` — writes the value followed by a newline
* `.write(value)` — writes the value without a trailing newline

Both `out` and `error` accept `Text`, `Bool`, `Int32`, `Int64`, `Decimal`, `Float64`, enum values, and value or object instances.

```kairo theme={null}
module Demo.ConsoleExample

import Pulse.Console

public func main(): Int32 {
    Pulse.Console.out.writeLine("Kairo speaks")
    return 0
}
```

<Tip>
  Always import the specific Pulse module you need rather than assuming console output is a global. This keeps your module dependencies explicit and your code portable across different execution environments.
</Tip>

***

## Astra First-Party Packages

Astra packages are optional, first-party libraries published by Astra Kairo. They are not bundled with the toolchain or runtime — you must declare each one as an explicit dependency in your `kairo.toml` manifest before you can use it. Once declared, add the corresponding `import` statement in any file that needs the package.

### Available Astra packages

<CardGroup cols={2}>
  <Card title="Astra.Money" icon="coins">
    Monetary values and arithmetic. `Money` is **not** a Core primitive — use this package whenever your domain requires currency-aware types.
  </Card>

  <Card title="Astra.Json" icon="braces">
    JSON serialization and deserialization. Convert Kairo values to and from JSON text.
  </Card>

  <Card title="Astra.Xml" icon="code">
    XML parsing and generation. Work with XML documents, elements, and attributes.
  </Card>

  <Card title="Astra.Configuration" icon="sliders">
    Application configuration loading. Read structured configuration from files or environment sources.
  </Card>

  <Card title="Astra.Http" icon="globe">
    HTTP client and server. Make outbound requests and handle inbound HTTP traffic.
  </Card>

  <Card title="Astra.Cryptography" icon="lock">
    Cryptographic primitives. Hashing, signing, encryption, and secure random generation.
  </Card>

  <Card title="Astra.FileSystem" icon="folder">
    File system access. Read, write, and navigate files and directories.
  </Card>

  <Card title="Astra.Database" icon="database">
    Database access. Connect to and query relational and other database systems.
  </Card>
</CardGroup>

<Note>
  `Money` is not a primitive in Kairo Core. `Astra.Money` is the canonical source for monetary values in Kairo applications. If your domain models prices, balances, or any currency-denominated quantity, declare `Astra.Money` as a dependency.
</Note>

### Adding an Astra package

To use any Astra package, add it to the `[dependencies]` section of your `kairo.toml` and then run `forge restore` to fetch and register the package.

```toml theme={null}
[dependencies]
Astra.Json = "*"
```

```bash theme={null}
forge restore
```

Then import the package in your source file and use it:

```kairo theme={null}
module Demo.JsonExample

import Astra.Json
import Pulse.Console

public value CustomerDto {
    id: Text
    name: Text
}

public func main(): Int32 {
    let customer: CustomerDto = CustomerDto {
        id: "CUST-001"
        name: "Acme Corp"
    }
    let json: Text = Astra.Json.serialize(customer)
    Pulse.Console.out.writeLine(json)
    return 0
}
```

<Note>
  Astra package documentation expands as each package stabilizes. Check the individual package reference pages for the most up-to-date API details.
</Note>