Skip to main content

Documentation Index

Fetch the complete documentation index at: https://internal.september.wtf/llms.txt

Use this file to discover all available pages before exploring further.

Every breaking change in the Engine gets a migration guide. Each guide explains what changed, what the new behavior is, and what code you need to update. For all changes (breaking and non-breaking), see the Changelog.

​
Active migrations

​
v2.2 → v2.3 — orchestrator extraction + super_thinking

Status: required if you’re using the orchestrator or the legacy effort parameter.

​
What changed

  1. Orchestrator removed. orchestrator.py is no longer in the Engine. It moved to bap-engine. If your deployment used the in-process orchestrator, switch to running bap-engine alongside the Engine.
  2. super_thinking replaces effort. The 4-level effort parameter (none/low/medium/high) was a poorly-calibrated knob. It’s replaced by a boolean super_thinking that turns extended thinking on or off explicitly.
  3. scripts/deploy.sh and scripts/pg-backup.sh removed. Postgres support is gone; the deploy script moved to bap-engine.
  4. src/infra/pg.py removed. SQLite is the only durable store.

​
Migration steps

If you used the in-process orchestrator:
  1. Set up bap-engine alongside the Engine. See bap-engine deployment docs.
  2. Point the upstream router (BAP) at the bap-engine orchestrator URL instead of the Engine’s orchestrator endpoint.
  3. The Engine continues to serve /execute and friends as before.
If you used the effort parameter: Before: 
{
  "message": "...",
  "task_id": "...",
  "effort": "high"
}
After: 
{
  "message": "...",
  "task_id": "...",
  "super_thinking": true
}
The mapping is effort: "high" → super_thinking: true; everything else → super_thinking: false. If you used the Postgres adapter: Postgres is no longer supported. The Engine is SQLite-only. Migrate your data to SQLite or run multiple Engines (one per user, each with its own SQLite brain).

​
Validation

After migration:
  • curl /health — should return ok.
  • Run a test /execute with super_thinking: true. Stream should include thinking_delta events.
  • Run regression evals — see Regression.

​
v1.x → v2.0 — pip package distribution

Status: required if you used a git-submodule install.

​
What changed

The Engine moved from git-submodule distribution to a pip package via private GitHub.

​
Migration steps

Before (Dockerfile snippet): 
ADD .gitmodules .
RUN git submodule update --init --recursive
RUN cp -r submodules/engine/migrations migrations
RUN cp -r submodules/engine/catalog catalog
After: 
RUN pip install git+https://github.com/septemberai/engine.git@v2.1.1
# migrations and catalog now ship inside the package
The Engine reads its bundled migrations and catalog automatically. Don’t bind-mount over them unless you’re customizing.

​
Validation

After migration:
  • python -c "import src; print(src.__version__)" should print the Engine version.
  • curl /health should return ok, with the migrations subsystem reporting all applied.

​
Migration playbook

For any upgrade, regardless of size:
  1. Read the changelog. Identify breaking changes.
  2. Read the relevant migration guides. This page.
  3. Back up the brain. Snapshot the volume or run /memory/export.
  4. Bring up the new Engine in a staging environment with a copy of the brain. Confirm /health returns ok.
  5. Run regression evals. Compare against the pre-upgrade baseline.
  6. Spot-check critical workflows. A coding agent run; a research agent run; a support tier-2 run with HITL.
  7. Roll out to production when the staging signal is green.
For high-stakes deployments, do a canary rollout: a small percentage of traffic on the new version for a few hours before flipping the rest.

​
When migration goes wrong

If the new Engine fails to start:
  • Check logs for migration errors. A failed migration leaves the brain in an inconsistent state.
  • Roll back to the previous version (the brain remains compatible with prior versions if no breaking schema changes happened).
  • Restore from snapshot if the brain is in a bad state.
If the new Engine starts but behaves oddly:
  • Run a regression eval to identify which behaviors regressed.
  • Check the Changelog for Changed entries that match the symptoms.
  • Roll back if the regressions are unacceptable.

​
Versioning

The Engine follows Semantic Versioning:
  • Major (X.0.0) — breaking changes. Always has a migration guide.
  • Minor (X.Y.0) — new features, no breaking changes.
  • Patch (X.Y.Z) — bug fixes, no new features.
Migration guides are required for major bumps; optional for minor bumps when behavior shifts non-breakingly.

​
See also

  • Changelog — every release.
  • Regression — checking behavior across versions.
  • Upgrade — operational steps for the deploy itself.