samwiseos-core

There are millions of AI skills for coding and work, and now for your day to day life as well.

SamwiseOS is a runtime for turning life changes into practical next steps.

Give it text like:

I bought heating solar panels from Brand X yesterday.

SamwiseOS extracts the life event and turns it into action proposals:

{
  "event": "Bought solar panels",
  "actions": [
    {
      "type": "store_document",
      "title": "Store solar panels documents"
    },
    {
      "type": "create_calendar_event",
      "title": "Schedule solar panels maintenance",
      "payload": {
        "due": "1 year"
      }
    },
    {
      "type": "create_todo",
      "title": "Handle solar panels setup"
    }
  ]
}

Behind that, it finds relevant skills, asks an LLM to produce a structured plan, validates the result, normalizes dates, and routes actions to providers. This repository contains the TypeScript runtime and CLI. The skills live in a separate repository so the engine and the knowledge base can evolve independently.

SamwiseOS Skills are natural language + simple metadata markdown files that anyone can write and contribute to. Available at https://github.com/appcalipse/samwiseos-skills.

Current Shape

Internal V0 is focused on being usable by developers:

• Stateless runSamwiseOS(request): Promise<RunResult> library API
• Buildless local CLI through pnpm cli
• Generated skill registry with BM25 + embeddings + RRF discovery
• LLM extraction of one or more life events
• LLM skill selection and expansion from retrieval candidates
• Provider-agnostic LLM requests with JSON response formatting
• Runtime validation and repair for structured outputs
• Runtime date and schedule normalization
• Stub action providers for local testing
• Ollama LLM and embedding provider
• OpenAI LLM and embedding provider
• Brave Search provider implementation
• Canonical behavior tests for 10 skill scenarios

Repositories

Use this repository beside the skills repository:

workspace/
  samwiseos-core/
  samwiseos-skills/

Clone both:

git clone https://github.com/appcalipse/samwiseos-core.git
git clone https://github.com/appcalipse/samwiseos-skills.git
cd samwiseos-core
pnpm install

Quick Start

Run everything with local fixture providers, no Ollama required:

pnpm embed-skills -- \
  --provider fixture \
  --skills-path ../samwiseos-skills

pnpm cli -- \
  --provider fixture \
  --input "I bought heating solar panels from Brand X yesterday."

Run with Ollama:

pnpm embed-skills -- \
  --skills-path ../samwiseos-skills \
  --ollama-url http://localhost:11434 \
  --embedding-model nomic-embed

pnpm cli -- \
  --ollama-url http://localhost:11434 \
  --model llama3.1 \
  --embedding-model nomic-embed \
  --input "We installed a new heat pump at home."

Run with OpenAI:

OPENAI_API_KEY=... pnpm embed-skills -- \
  --provider openai \
  --skills-path ../samwiseos-skills

OPENAI_API_KEY=... pnpm cli -- \
  --provider openai \
  --input "We installed a new heat pump at home."

The generated skill registry is stored under .samwiseos/skills/ by default and is git-ignored. Regenerate it after changing skill text or switching embedding models. Normal runs read this registry, so --skills-path is only needed when running embed-skills.

CLI

Show help:

pnpm cli -- --help
pnpm cli -- run --help
pnpm cli -- embed-skills --help

Useful flags for embed-skills:

• --skills-path <path>: source skill repository. Default: ../samwiseos-skills
• --skill-registry-path <path>: generated registry output. Default: .samwiseos/skills
• --provider <ollama|openai|fixture>: embedding provider. Default: ollama
• --ollama-url <url>: Ollama base URL. Default: http://localhost:11434
• --openai-url <url>: OpenAI-compatible base URL. Default: https://api.openai.com/v1
• --openai-api-key <key>: OpenAI API key. Defaults to OPENAI_API_KEY
• --embedding-model <name>: embedding model. Default: nomic-embed for Ollama, text-embedding-3-small for OpenAI
• --verbose: write debug traces to stderr
• --help, -h: show command help

Verbose mode keeps the normal RunResult JSON on stdout and writes debug traces to stderr:

pnpm cli -- \
  --verbose \
  --ollama-url http://localhost:11434 \
  --model llama3.1 \
  --embedding-model nomic-embed \
  --input "I bought heating solar panels from Brand X yesterday."

Use --verbose-prompts to include the full system prompts and user prompts sent to the LLM.

Optional Brave Search key:

BRAVE_API_KEY=... pnpm cli -- --input "I moved to Portugal from Brazil."

Library Usage

import {
  OllamaProvider,
  OpenAIProvider,
  runSamwiseOS,
} from "samwiseos-core";

const ollama = new OllamaProvider({
  baseUrl: "http://localhost:11434",
  model: "llama3.1",
  embeddingModel: "nomic-embed",
});

const result = await runSamwiseOS({
  input: {
    raw_content: "I bought heating solar panels from Brand X yesterday.",
  },
  context: {
    locale: "pt-PT",
    timezone: "Europe/Lisbon",
    country: "PT",
  },
  skillRegistryPath: ".samwiseos/skills",
  skillEmbeddingProvider: "ollama",
  skillEmbeddingModel: "nomic-embed",
  providers: {
    llm: ollama,
    embeddings: ollama,
  },
});

OpenAI can be used through the same provider boundary:

const openai = new OpenAIProvider({
  model: "gpt-5.5",
  embeddingModel: "text-embedding-3-small",
});

const result = await runSamwiseOS({
  input: {
    raw_content: "I bought heating solar panels from Brand X yesterday.",
  },
  skillRegistryPath: ".samwiseos/skills",
  skillEmbeddingProvider: "openai",
  skillEmbeddingModel: "text-embedding-3-small",
  providers: {
    llm: openai,
    embeddings: openai,
  },
});

Development

pnpm typecheck
pnpm lint
pnpm test
pnpm build

pnpm cli and pnpm embed-skills run TypeScript source directly for local development. pnpm build still emits dist/ for package/bin usage.