  .           .                 .            .               .
         .            .      .             .          .
  .            .                 .                 .
        .            .      .            .        .           .
 .            .                 .           .                 .
        .            .                 .            .
  .            .           .                 .           .
         .            .            .       .            .
  .                 .            .            .
        .       .            .                 .       .
 .            .                 .            .
        .            .      .            .            .
  .            .                 .                 .
         .            .            .       .
  .                 .                 .            .

              .  : .
           .   .----.   .
         .  .-(      )-.
        .-(              )-.
      .(    .----.          ).
    .(   . (      )__         ).
   (   .  (          )__ .---.  )
  (  .   (   . : . .    (     )  )
  ( .  .(  . : : .   . . : .   ). )
   '(   .(     )__ .__(     ).   )'
     '-(  . : .   (   . : .   )-'
       '-(     )-' '-(     )-'
          '---'   .   '---'
             .  : . .

        .  .
     .__(   )__.
   _(           )_
  (   .   :   .   )
  ( .   .   .   . )
   '(   .   .   )'
     '-( )-( )-'
        '   '
       .  .

        .  : .
      .  .---.                 .  .
    . .-(     )-.  .        .---.
   .-(           )---------(     )-.
 .(    .---.                        ).
(   . (     )__       .---.   . : .   )
(  . (         )-----(     )__     .  )
 '(   (   . : . .    . : .    ) .    )'
   '-( ( . : : .   . . : .   )   )-'
      '-(     )---(     )---'   .
         '---'     '---'
            .  : .    .

             .  : .
          .   .-----.  .   .  ~  ~
        .  .-(       )__     ~  ~
      . .-(             )________
     .-(    .---.                )__
   .(    . (     )__      . : .     )
  (   .   (         )____        .   )
  ( .   .(  . : . .      ) .   .    )
   '(  . ( . : : .   .  )      .  )'
     '(   .(     )__ . ) .     )-'
       '-(  . : .   (   )---.-'
         '-(     )-' '-(   )'
            '---'       '-'
               .  : . .

        .  : .  .  : .
    ._______________________.
  .(                         ).
 (    .   . : . .   . : . .    )
 (  .   . : : .   . : : .   .  )
  '(   .     .     .     .   )'
    '-( )--( )---( )--( )---'
       '    '     '    '
      .  : .       .  :

              .  : .
           .   .----.   .
         .  .-(      )-.
        .-(              )-.
      .(    .----.          ).
    .(   . (      )__         ).
   (   .  (          )__ .---.  )
  (  .   (   . : . .    (     )  )
  ( .  .(  . : : .   . . : .   ). )
   '(   .(     )__ .__(     ).   )'
     '-(  . : .   (   . : .   )-'
       '-(     )-' '-(     )-'
          '---'   .   '---'
             .  : . .

        .  .
     .__(   )__.
   _(           )_
  (   .   :   .   )
  ( .   .   .   . )
   '(   .   .   )'
     '-( )-( )-'
        '   '
       .  .

        .  : .                     .  : .
     .__(     )__.              .__(     )__.
   _(             )__        .__(            )__
 _(    .   .         )______(     .    .        )_
(   .        .    .   .        .          .    .  )
( .    .   .        .   .. .       .   .         .)
 '(   .       .   .          .   .      .    .  )'
   '-(    .            .            .       )-'
      '-(   )-.______.--(   )-.______.--(   )-'
         '-'             '-'             '-'
            .  : .          .  : .          .  : .

              .  : .                                 .  : .
           .__(     )__                           .__(     )__
       .__(            )__                     .__(           )__
    ._(     .    .        )__               ._(    .    .        )__
  _(     .            .      )_____________(    .            .      )_
 (   .        .    .      .     .       .    .        .    .      .   )
 ( .    .   .        .  .. .         .          .   .        .  .. .  )
  '(   .       .   .          .   .       .   .       .   .         . )'
    '-(     .            .         .   .            .         .     )-'
       '-(   )-.________.-(   )-.________.-(   )-.________.-(   )-'
          '-'                '-'              '-'              '-'
             .  : .               .  : .               .  : .

        .  : .  .  : .
    ._______________________.
  .(                         ).
 (    .   . : . .   . : . .    )
 (  .   . : : .   . : : .   .  )
  '(   .     .     .     .   )'
    '-( )--( )---( )--( )---'
       '    '     '    '
      .  : .       .  :

@0.1.15

Theorum

A TypeScript kernel for typed agent profiles and deterministic turns.

  .           .                 .            .               .
         .            .      .             .          .
  .            .                 .                 .
        .            .      .            .        .           .
 .            .                 .           .                 .
        .            .                 .            .
  .            .           .                 .           .
         .            .            .       .            .
  .                 .            .            .
        .       .            .                 .       .
 .            .                 .            .
        .            .      .            .            .
  .            .                 .                 .
         .            .            .       .
  .                 .                 .            .

              .  : .
           .   .----.   .
         .  .-(      )-.
        .-(              )-.
      .(    .----.          ).
    .(   . (      )__         ).
   (   .  (          )__ .---.  )
  (  .   (   . : . .    (     )  )
  ( .  .(  . : : .   . . : .   ). )
   '(   .(     )__ .__(     ).   )'
     '-(  . : .   (   . : .   )-'
       '-(     )-' '-(     )-'
          '---'   .   '---'
             .  : . .

        .  : .
      .  .---.                 .  .
    . .-(     )-.  .        .---.
   .-(           )---------(     )-.
 .(    .---.                        ).
(   . (     )__       .---.   . : .   )
(  . (         )-----(     )__     .  )
 '(   (   . : . .    . : .    ) .    )'
   '-( ( . : : .   . . : .   )   )-'
      '-(     )---(     )---'   .
         '---'     '---'
            .  : .    .

        .  : .  .  : .
    ._______________________.
  .(                         ).
 (    .   . : . .   . : . .    )
 (  .   . : : .   . : : .   .  )
  '(   .     .     .     .   )'
    '-( )--( )---( )--( )---'
       '    '     '    '
      .  : .       .  :

        .  : .                     .  : .
     .__(     )__.              .__(     )__.
   _(             )__        .__(            )__
 _(    .   .         )______(     .    .        )_
(   .        .    .   .        .          .    .  )
( .    .   .        .   .. .       .   .         .)
 '(   .       .   .          .   .      .    .  )'
   '-(    .            .            .       )-'
      '-(   )-.______.--(   )-.______.--(   )-'
         '-'             '-'             '-'
            .  : .          .  : .          .  : .

Overview

A unified runtime
for agentic execution.

Theorum turns ad-hoc agent scripts into a typed execution kernel. One contract per agent — predictable at every boundary.

Pillars

Profile

  .           .                 .            .               .
         .            .      .             .          .
  .            .                 .                 .
        .            .      .            .        .           .
 .            .                 .           .                 .
        .            .                 .            .
  .            .           .                 .           .
         .            .            .       .            .
  .                 .            .            .
        .       .            .                 .       .
 .            .                 .            .
        .            .      .            .            .
  .            .                 .                 .
         .            .            .       .
  .                 .                 .            .

              .  : .
           .   .----.   .
         .  .-(      )-.
        .-(              )-.
      .(    .----.          ).
    .(   . (      )__         ).
   (   .  (          )__ .---.  )
  (  .   (   . : . .    (     )  )
  ( .  .(  . : : .   . . : .   ). )
   '(   .(     )__ .__(     ).   )'
     '-(  . : .   (   . : .   )-'
       '-(     )-' '-(     )-'
          '---'   .   '---'
             .  : . .

        .  : .
      .  .---.                 .  .
    . .-(     )-.  .        .---.
   .-(           )---------(     )-.
 .(    .---.                        ).
(   . (     )__       .---.   . : .   )
(  . (         )-----(     )__     .  )
 '(   (   . : . .    . : .    ) .    )'
   '-( ( . : : .   . . : .   )   )-'
      '-(     )---(     )---'   .
         '---'     '---'
            .  : .    .

        .  : .  .  : .
    ._______________________.
  .(                         ).
 (    .   . : . .   . : . .    )
 (  .   . : : .   . : : .   .  )
  '(   .     .     .     .   )'
    '-( )--( )---( )--( )---'
       '    '     '    '
      .  : .       .  :

        .  : .                     .  : .
     .__(     )__.              .__(     )__.
   _(             )__        .__(            )__
 _(    .   .         )______(     .    .        )_
(   .        .    .   .        .          .    .  )
( .    .   .        .   .. .       .   .         .)
 '(   .       .   .          .   .      .    .  )'
   '-(    .            .            .       )-'
      '-(   )-.______.--(   )-.______.--(   )-'
         '-'             '-'             '-'
            .  : .          .  : .          .  : .

Package map

Theorum ──┬──  ─────────┬──  ──────────────────┬── 
          │                   │                            ├── 
          │                   │                            ├── 
          │                   │                            ├── 
          │                   │                            └──  ──────┬── 
          │                   │                                             ├── 
          │                   │                                             └── 
          │                   ├──  ────────────────┬── 
          │                   │                            ├── 
          │                   │                            ├── 
          │                   │                            ├── 
          │                   │                            └── 
          │                   └── 
          │
          ├──  ──────┬── 
          │                   ├── 
          │                   ├── 
          │                   ├── 
          │                   └── 
          │
          ├──  ─────┬── 
          │                   ├── 
          │                   ├── 
          │                   ├── 
          │                   └── 
          │
          ├──  ──┬── 
          │                   └── 
          │
          ├──  ────────────┬── Commands ────────────────┬── 
          │                   │                            ├── 
          │                   │                            ├── 
          │                   │                            ├── 
          │                   │                            └── 
          │                   └──  ──────────────────┬── 
          │                                                └── 
          │
          ├──  ── 
          │
          └──  ──

Define a profile

A profile is the contract for one agent: identity, models, tools, inputs, outputs, and guardrails.

1 · Install

Add theorum to your project, then import the profile APIs.

npm install theorum

import { defineProfile, registerProfile } from "theorum";

2 · Describe agent

Every profile has an id, a handle, and a system instruction the model receives each turn.

defineProfile({
  : "mermaid",
  : {
    : "mermaid",
    : true,
    :
      "Turn requests into Mermaid diagrams. Ask when the request is too vague.",
  },

3 · Define models

Select a provider and the models this agent may use. Each model sets thinking levels, token limits, and optional compaction.

  : {
    : "geminiInteractions",
    : "google",
    : ["flash", "pro"],
    : {
      : {
        : "gemini-3.5-flash-lite",
        : {
          : "medium",
          : "minimal",
        },
        : ["minimal", "low", "medium", "high"],
        : {
          : "auto",
          : "none",
        },
        : 8192,
        : 1,
        : ["googleMaps", "urlContext"],
      },
      : {
        : "gemini-3.7-flash",
        : {
          : "high",
          : "low",
        },
        : ["low", "medium", "high"],
        : {
          : "auto",
          : "auto",
        },
        : 64000,
        : 1,
        : [],
      },
    },
    : {
      : "flash",
      : "pro",
    },
    : {
      : "low",
      : "high",
    },
    : ["thinking"],
    : 1,
  },

4 · Configure tools

tools.allow is the maximum set of tools the agent can call. Anything outside that list is rejected.

  : {
    : ["googleSearch", "googleMaps", "urlContext"],
  },

5 · Allow inputs

Declare which text, file, and voice inputs the agent accepts on a turn.

  : {
    : true,
    : {
      : ["image/png", "image/jpeg", "image/webp", "application/pdf", "text/plain", "text/markdown"],
    },
    : {
      : ["audio/webm", "audio/wav", "audio/mpeg"],
    },
    : 5,
  },

6 · Describe outputs

Configure how the agent responds: plain text, structured JSON, images, or speech.

  : {
    : "mermaidTurn",
    : {
      : {
        : (source) => ({
          isValid: typeof source === "string" && source.trim().length > 0,
          error: "diagram.mermaid must be a non-empty string",
        }),
      },
      : 3,
      : "Return valid Mermaid only in diagram.mermaid.",
    },
    : {
      : true,
      : true,
    },
    : {
      : ["length", "stream_incomplete", "provider_error"],
      : ["length", "stream_incomplete"],
    },
  },

7 · Set guardrails

Control canary fencing, input sanitization, sensitive-data redaction, quotas, and egress checks.

  : {
    : true,
    : true,
    : true,
    : {
      : 20,
    },
  },

Loading canvas…