Skip to content

finger-gun/sisu

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

166 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

SISU Logo

A TypeScript framework for reliable AI agents with full transparency and control. Inspired by the Finnish concept of sisu calm determination under pressure.

Build AI agents that just work.

No surprises. Explicit middleware, typed tools, deterministic control flow. Full control. Compose planning, routing, and safety like Express apps. Total visibility. Built-in tracing, logging, and debugging out of the box. Provider-agnostic. OpenAI, Anthropic, Ollama, or bring your own.

Tests CodeQL License Downloads PRs Welcome


Quick Start

Install

pnpm add @sisu-ai/core @sisu-ai/adapter-openai \
         @sisu-ai/mw-register-tools @sisu-ai/mw-tool-calling \
         @sisu-ai/mw-conversation-buffer @sisu-ai/mw-trace-viewer \
         @sisu-ai/mw-error-boundary zod dotenv

Your First Agent

import "dotenv/config";
import { Agent, createCtx, type Tool } from "@sisu-ai/core";
import { registerTools } from "@sisu-ai/mw-register-tools";
import { inputToMessage, conversationBuffer } from "@sisu-ai/mw-conversation-buffer";
import { errorBoundary } from "@sisu-ai/mw-error-boundary";
import { toolCalling } from "@sisu-ai/mw-tool-calling";
import { openAIAdapter } from "@sisu-ai/adapter-openai";
import { traceViewer } from "@sisu-ai/mw-trace-viewer";
import { z } from "zod";

const weather: Tool<{ city: string }> = {
  name: "getWeather",
  description: "Get weather for a city",
  schema: z.object({ city: z.string() }),
  handler: async ({ city }) => ({ city, tempC: 21, summary: "Sunny" }),
};

const ctx = createCtx({
  model: openAIAdapter({ model: "gpt-4o-mini" }),
  input: "What is the weather in Stockholm?",
  systemPrompt: "You are a helpful assistant.",
});

const app = new Agent()
  .use(errorBoundary())
  .use(traceViewer())
  .use(registerTools([weather]))
  .use(inputToMessage)
  .use(conversationBuffer({ window: 8 }))
  .use(toolCalling);

await app.handler()(ctx);

Open traces/viewer.html to see exactly what happened.


Why Sisu

You're dealing with... Sisu gives you...
"Where did my tokens go?" A trace viewer showing every token, cost, and decision
"The tool loop broke and I can't debug it" Explicit control flow you can read, test, and step through
"Can't swap providers without rewriting" Provider-agnostic adapters — change one line
"Secrets keep leaking into my logs" Automatic redaction of API keys and sensitive data
"Production bugs are impossible to trace" Structured logging and HTML traces for every run

Built-in Observability

HTML Trace Viewer

HTML Trace Viewer

Every run auto-generates an interactive HTML trace: token usage and costs, tool calls with timing, full conversation history, and error details when things break.

CLI Trace Logs

CLI Trace Logs

Structured, color-coded terminal output. No more parsing walls of JSON.


Core Concepts

Everything is Middleware

Compose your agent pipeline like an Express app. Each middleware does one thing well.

const app = new Agent()
  .use(errorBoundary())
  .use(traceViewer())
  .use(registerTools([...]))
  .use(toolCalling);

One Context, Zero Magic

Everything flows through a single typed ctx. No hidden state, no side channels.

(ctx, next) => {
  ctx.messages.push(...)  // Modify state
  await next()            // Pass to next middleware
  console.log(ctx.result) // React to changes
}

Typed Tools

Zod schemas validate tool inputs automatically. Define once, use safely everywhere.

const tool: Tool = {
  name: "searchDocs",
  schema: z.object({ query: z.string() }),
  handler: async ({ query }) => { /* ... */ },
};

Control Flow is Just Code

Sequence, branch, loop, run in parallel, or define a DAG. Readable, testable, no hidden behavior.

import { sequence, branch, parallel, graph } from '@sisu-ai/mw-control-flow';

.use(sequence([
  classifyIntent,
  branch({
    'search': searchPipeline,
    'chat': conversationPipeline
  })
]))

Swap Providers in One Line

const model = openAIAdapter({ model: "gpt-4o-mini" });
// const model = anthropicAdapter({ model: 'claude-sonnet-4' });
// const model = ollamaAdapter({ model: 'llama3.1' });

The OpenAI adapter works with any compatible API (LM Studio, vLLM, OpenRouter):

const model = openAIAdapter({
  model: "gpt-4o-mini",
  baseUrl: "http://localhost:1234/v1",
});

Ecosystem

Adapters

Provider Package Tools Streaming Vision
OpenAI @sisu-ai/adapter-openai
Anthropic @sisu-ai/adapter-anthropic
Ollama @sisu-ai/adapter-ollama

Middleware

Category Packages
Control Flow sequence · branch · parallel · graph
Tool Management registerTools · toolCalling
Conversation conversationBuffer · contextCompressor
Safety errorBoundary · guardrails · invariants
Observability traceViewer · usageTracker
Advanced rag · reactParser · skills · orchestration

Tools

Category Packages
Web webFetch · webSearch · wikipedia
Cloud awsS3 · azureBlob
Dev terminal · githubProjects
Data vectorChroma · extractUrls · summarizeText

Run an Example

# OpenAI
cp examples/openai-hello/.env.example examples/openai-hello/.env
pnpm run ex:openai:hello
open examples/openai-hello/traces/trace.html

# OpenAI orchestration
pnpm run ex:openai:orchestration
pnpm run ex:openai:orchestration-adaptive

# Ollama (local, no API key needed)
ollama serve && ollama pull llama3.1
pnpm run ex:ollama:hello

25+ examples covering streaming, vision, RAG, control flow, orchestration, guardrails, and more in /examples.


Configuration

# LLM Providers
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
OLLAMA_BASE_URL=http://localhost:11434    # default

# Logging
LOG_LEVEL=info        # debug | info | warn | error
DEBUG_LLM=1           # log adapter requests on errors

# Tracing
TRACE_HTML=1           # auto-generate HTML traces
TRACE_JSON=1           # auto-generate JSON traces
TRACE_STYLE=dark       # light | dark

Development

pnpm install           # install dependencies
pnpm build             # build all packages (Turbo-cached)
pnpm test              # run all tests
pnpm test:coverage     # run with coverage (target ≥80%)
pnpm dev               # watch mode
pnpm lint:fix          # fix lint issues
pnpm typecheck         # type check all packages

Built with Turbo, pnpm workspaces, Vitest, and Changesets.


Documentation

CorePackage docs · Error types

AdaptersOpenAI · Anthropic · Ollama

All middleware packages
All tool packages
All examples

Anthropichello · control-flow · stream · weather

Ollamahello · stream · vision · weather · web-search

OpenAIhello · weather · stream · vision · reasoning · react · control-flow · branch · parallel · graph · orchestration · orchestration-adaptive · guardrails · error-handling · rag-chroma · web-search · web-fetch · wikipedia · terminal · github-projects · server · aws-s3 · azure-blob


Contributing

We build Sisu in the open. Contributions welcome.

Contributing Guide · Report a Bug · Request a Feature · Code of Conduct


Star on GitHub if Sisu helps you build better agents.

Quiet, determined, relentlessly useful.

Apache 2.0 License

About

Grit-powered agent framework

Resources

License

Code of conduct

Contributing

Stars

Watchers

Forks

Packages

 
 
 

Contributors