SDK Thesis Lifecycle Patterns

When to use

• Building a TypeScript service that creates/evolves theses programmatically
• Integrating thesis lifecycle into a custom dashboard
• Adding thesis automation to an existing app

Prerequisites

npm install @spfunctions/[email protected]
export SF_API_KEY="sf_..."  # required — theses are user-scoped

The 8-verb lifecycle

create → context → signal → evaluate → augment → fork → publish → unpublish

SDK setup

import { SimpleFunctions } from "@spfunctions/sdk"

const sf = new SimpleFunctions({
  apiKey: process.env.SF_API_KEY,
  baseUrl: process.env.SF_API_URL ?? "https://simplefunctions.dev",
})

List theses

const theses = await sf.theses.list({
  status: "active", // "active" | "killed" | "published" | "all"
  limit: 10,
})

console.log(theses.map(t => ({
  id: t.id,
  title: t.title,
  confidence: t.confidence,
  status: t.status,
  publishedSlug: t.publishedSlug,
})))

Get one thesis (with tree)

const thesis = await sf.theses.get("thesis-id")

console.log({
  title: thesis.title,
  confidence: thesis.confidence,
  nodes: thesis.tree?.nodes,
  edges: thesis.edges,
  recentSignals: thesis.signals?.slice(-5),
})

The full causal tree is in thesis.tree. Each node has its own confidence + linked markets.

Create a thesis

For programmatic creation, use direct HTTP (SDK wrapper may be deferred per stability classification):

const created = await fetch("https://simplefunctions.dev/api/thesis/create", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SF_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Fed cuts rates by July driven by jobs softening + CPI ≤ 2.5%",
  }),
}).then(r => r.json())

console.log(created.id, created.tree)

The server's LLM classifier rejects shell-escape garbage and expands the thesis into a causal tree. Returns the thesis id.

Inject a signal

const signal = await fetch(`https://simplefunctions.dev/api/thesis/${thesisId}/signal`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SF_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    content: "Powell speech: 'job market is softening more than expected'",
    source: "news",
  }),
}).then(r => r.json())

The server appends the signal, schedules the next monitor cycle, and updates affected node confidences.

Evaluate (deep)

const evaluation = await fetch(`https://simplefunctions.dev/api/thesis/${thesisId}/evaluate`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SF_API_KEY}`,
    "Content-Type": "application/json",
  },
}).then(r => r.json())

console.log({
  confidenceDelta: evaluation.confidenceDelta,
  recommendations: evaluation.positionRecommendations,
  killCheck: evaluation.killConditionCheck,
})

Uses the heavy evaluation model — expensive, slow. Run periodically (daily, after major signals), not on every minor update.

Heartbeat config

const heartbeat = await fetch(`https://simplefunctions.dev/api/thesis/${thesisId}/heartbeat`, {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${process.env.SF_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    cadence: "1h",
    evaluationModelTier: "standard",
    monthlyBudgetUsd: 5.00,
    killConditions: [
      { type: "node_confidence_below", node: "n1.2", threshold: 0.3 },
      { type: "drawdown_above", percent: 15 },
    ],
    closedLoop: {
      entry: false,
      exit: false,
    },
  }),
}).then(r => r.json())

See sf-thesis-monitor skill for kill condition types and cadence guidance.

Publish

const published = await fetch(`https://simplefunctions.dev/api/thesis/${thesisId}/publish`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SF_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    slug: "fed-rate-cut-july",
  }),
}).then(r => r.json())

console.log(published.publishedUrl) // "https://simplefunctions.dev/thesis/fed-rate-cut-july"

Slugs are normalized server-side (/[^a-z0-9-]/g strip, max 60 chars).

Full programmatic lifecycle

async function buildAndMonitorThesis(text: string, slug: string) {
  // 1. Create
  const { id } = await fetch("https://simplefunctions.dev/api/thesis/create", {
    method: "POST",
    headers: { "Authorization": `Bearer ${process.env.SF_API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ text }),
  }).then(r => r.json())
  
  // 2. Pull initial tree
  const initial = await sf.theses.get(id)
  console.log("Initial tree:", initial.tree?.nodes?.length, "nodes")
  
  // 3. Configure heartbeat
  await fetch(`https://simplefunctions.dev/api/thesis/${id}/heartbeat`, {
    method: "PATCH",
    headers: { "Authorization": `Bearer ${process.env.SF_API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      cadence: "1h",
      evaluationModelTier: "standard",
      monthlyBudgetUsd: 5.00,
    }),
  })
  
  // 4. Publish
  const { publishedUrl } = await fetch(`https://simplefunctions.dev/api/thesis/${id}/publish`, {
    method: "POST",
    headers: { "Authorization": `Bearer ${process.env.SF_API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ slug }),
  }).then(r => r.json())
  
  return { thesisId: id, publishedUrl }
}

const result = await buildAndMonitorThesis(
  "Fed cuts rates by July driven by jobs softening + CPI ≤ 2.5%",
  "fed-rate-cut-july"
)
console.log(result)

Errors

• Thesis creation rejected (`status: 400`): LLM classifier filtered the text. Make it a clean directional claim.
• `HttpError 403` on signal/evaluate: not the thesis owner. Verify SF_API_KEY matches the user.
• Slug conflict on publish: slug already taken. Pick another or unpublish first.

Related skills

• sf-sdk-quickstart — install + first call
• sf-thesis-build — CLI workflow for the same lifecycle
• sf-thesis-monitor — heartbeat config details
• sf-sdk-portfolio — intents linked to thesis evaluations

Reference docs

• <https://docs.simplefunctions.dev/guides/authenticated-read-sdk>
• <https://docs.simplefunctions.dev/build/thesis-lifecycle>
• <https://docs.simplefunctions.dev/api-reference/thesis>
• <https://docs.simplefunctions.dev/guides/stability-side-effects>