System 1: Teach a decision. Run it locally.

System 1 is not an LLM. Show it examples of a repeatable decision—such as which team should receive a message—then check the skill and reuse it locally. Its default path uses small numerical decision heads and fixed text features: no language-model weights to download, no token generation, and no GPU required. Optional MLX support runs decision-head matrix operations on Apple Silicon.

Choose a decision → show examples → check a candidate → adopt → correct and compare.

Performance · Start teaching · Automatic teachers · Evidence · Integrations · Documentation

Why it is fast

Small skills make fast local decisions. After teaching, System 1 applies a compact numerical decision head. Each request avoids a teacher API round trip and language-model token generation. The default saved skill needs no language-model weights or model server. Some optional research adapters use pretrained text encoders; their reports count those separate weights and encoding costs. They still produce bounded decisions rather than generated text.

These are NumPy CPU measurements on an Apple M4 Pro, excluding startup, receipt signing and downstream work. Skill-file sizes exclude the installed runtime and dependencies. Optional MLX supports Apple Silicon acceleration; its speed benefit depends on the workload. See the reproducible results and quality limits.

The payoff is useful for repeated routing, classification and structured choices. Quality depends on the taught task; uncertain answers still need review.

Quickstart

Use Python 3.11 or newer. To follow the editable lesson, start from a repository checkout:

git clone https://github.com/steph4n-gh/system1.git
cd system1
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

On Windows, activate the environment with .venv\Scripts\activate instead.

Prefer to teach by doing? Run python -m examples.teaching_by_doing and open http://127.0.0.1:8791/. File fictional document cards into folders; each choice becomes a lesson. Review a candidate, compare its answers, then explicitly adopt a passing revision. Correct earlier choices while keeping the approved skill available, and download that skill for reuse. The document workspace explains the flow and reports its sample results, including mistakes.

1. Choose one decision

We will choose between billing and support. Payment questions go to billing; broken software goes to support. You decide the rule.

2. Show it examples

An example is an input paired with the answer you want. That answer is what “label” means:

The editable lesson file contains eight such pairs. Run it:

python examples/teach_skill.py

This teaches a small skill, saves .system1/support-route.s1m, reloads it and tries “Please refund this payment.” No API key or teacher service is involved.

3. Check the answer

The starter prints:

Suggested team: billing
Needs review: True

billing is its best guess. Needs review means a person should still decide. Eight examples show the process; they do not establish reliable automatic routing. To judge a skill, check different messages: count both wrong answers and requests for review. A saved file alone does not mean the skill is ready.

For a complete, larger demonstration with separate teaching, uncertainty checks and final evaluation, run python examples/support_triage.py. It routes to four departments and reports every result, including mistakes. The first-skill walkthrough explains how to do this with your own messages.

4. Reuse the saved skill

The file is the portable skill. Load it without reteaching or calling the teacher:

from system1 import CompiledSystemOneModel, System1Engine

skill = CompiledSystemOneModel.load(".system1/support-route.s1m")
engine = System1Engine(skill.schema, model=skill, strict_mode=True)
answer = engine.decide("Please refund this payment", record_receipt=False)
print(answer.values["team"])
print("Needs review:", answer.is_ambiguous)

The application honors the review flag before using an answer automatically. Saving and reloading preserves uncertainty; it does not turn the starter's uncertain answer into an approved one.

5. Improve with a correction

For “The payment page crashes,” our desired answer is support: the issue is broken software. Correct the lesson, then check different messages for both teams before adopting a revision.

The TeachingSession workflow, introduced in System 1 1.1.0, keeps that process together. First create a session with separate lessons and checks. Once initialized, a correction looks like this:

from system1 import TeachingSession

# Reopen a session created with a schema and separate labeled checks.
session = TeachingSession(".system1/support-session")
session.record("The payment page crashes", "support")
report = session.assess()   # Build and compare; the current skill keeps serving.
print(report["candidate"], report["regressions"], report["reasons"])
# After reviewing a passing report: session.adopt()

The report separates raw accuracy, accepted mistakes, review rate and regressions. Adoption requires the exact passing candidate and unchanged data; a failed revision does not replace the working skill. This first workflow supports one text ChoiceField. The eight-example starter and lower-level teaching APIs remain available.

6. Qualify and retain approved revisions

In 1.2.0, assess with require_qualification=True when adoption must also pass separate qualification. Supply a reserved, independently labeled cohort and its source to session.qualify(...) before adopting. Reports distinguish accepted correctness from the fraction answered without review, and insufficient evidence continues to block adoption. Software cannot establish that supplied labels or sampling are valid; see the qualification guide.

Approved bytes and their evidence remain in session.history. Restore a known revision explicitly with session.rollback(revision); lessons stay available, and another adoption needs a new assessment. session.decision_details(text) shows the approved revision and observable review reasons. These additions do not make a rejected workload qualified.

Observe a teacher, then take over

Once the lesson format makes sense, another source can supply the answers: a colleague, reviewed historical decisions, existing rules, a conventional classifier, Jev, Gemini or another API. JSON stores lessons; a teacher callback supplies them while a program runs. An LLM can teach a skill without the resulting skill becoming an LLM or inheriting the teacher's general knowledge.

python examples/observe_routing.py

This demonstrates the same journey automatically: observe answers, teach, validate, switch to local decisions, then save and reload. Its default teacher is an inspectable rule over synthetic tickets. An optional live Jev mode and custom callbacks use the same observation workflow.

The teacher stays responsible until the candidate qualifies. Local execution can still request review. Promotion depends on evidence, not a promised number of turns. Use PromotionPolicy(min_accepted_agreement=.95) when you need the stronger accepted-agreement qualification added in 1.0.2; teacher agreement and independent correctness are separate checks.

Benchmarks

The published public-data evaluation measures three fixed bounded tasks. These 1,301 cases were kept out of teaching and calibration in the original experiment:

The report includes original labels, fixed splits, every error and a classical TF-IDF/logistic-regression baseline. That baseline matched raw correctness on banking and assistant, scored lower on SMS, and ran faster locally on all three.

Automatic observation is measured separately. Actual Jev and Gemini 2.5 Flash each enabled six-intent assistant takeover after 358 observations under the original default policy: 171/180 test requests accepted, 167/171 correct, with no further teacher calls and matching saved/reloaded results.

Quality does not transfer automatically to new traffic. Later authored SMS probes reached only 27/33 correct accepted answers (81.8%); stronger-policy banking and assistant takeovers remained deferred. The public-email experiments retain a source-shift failure and a subsequent retrospective improvement. The full-scope n8n skills and seven-category Inbox Zero pilot remain unqualified. The workload and evidence index distinguishes these scopes, baselines, successful checks and unresolved failures. Reused test sets are regression evidence, not fresh independent confirmation.

The new real-document workflow test used all five BBC news topics and a 400-article holdout. Targeted feedback reduced accepted mistakes from 16 to 8 while accepted decisions fell from 373 to 337. Its one-point raw-accuracy gain was inconclusive. All candidates were rejected by the unchanged default adoption gates. This demonstrates a quality/review tradeoff and a working refusal path, not automatic qualification of a document skill.

To check the primary teaching examples and the recorded Jev comparison:

python benchmarks/quality/evaluate_release.py

This runs offline and fails if a primary demonstration misses its 95% accepted correctness / 80% acceptance point targets. See the quality index for all reproduction commands, confidence intervals and historical experiments.

Integrations

The project is packaged on PyPI as system1. To add it to an existing Python project:

python -m pip install system1

After checking the skill on your task, connect it to your application. The core supports choice, boolean, multi-choice and score outputs; uncertainty tells the application when to request review.

Policy guard

If a decision would execute a tool, add an explicit permission policy. The executable guard quickstart shows PolicyEngine, an enforcement guard and a durable ledger. Optional software Ed25519 signatures (RFC 8032) and a SHA-256 hash-chained ledger provide audit evidence. A classifier's suggested answer alone is not permission to act. See deployment boundaries for identity, network and enforcement responsibilities.

Examples and research

Run these labs from a repository checkout. Full n8n research artifacts and raw results remain in Git and are excluded from the Python package distributions.

The example catalog links every teaching, observation, game and integration example with its scope. The architecture, technical brief and whitepaper explain the implementation and evidence. The papers are maintainer-authored, not peer-reviewed publications. Established numerical methods power the product; the practical value is the complete path from examples to a checked local skill.

Release and development

Version 1.2.0: adds candidate-bound independent qualification, retained approved revisions and explicit rollback, clearer review evidence, and optional logistic fitting in teaching sessions. Python, CLI and the document workspace share the same lifecycle. Existing compiler/engine APIs and saved skills remain supported; TF-IDF skills require a 1.1.0-or-newer reader.

The document workspace and gaming/integration labs remain experimental examples run from a repository checkout. Publishing the runtime does not qualify their workloads or include every research artifact in Python distributions. See the 1.2.0 release report, changelog, 1.0.3 security release and 1.0 migration guide. The legacy reflex import namespace remains a compatibility alias.

python -m pip install -e '.[dev,langchain]'
python -m pytest tests/ -q

CI checks Linux/macOS tests, documentation, built distributions and real LangChain dispatch. See contributing and security reporting.

Apache License 2.0.