Migrating from symfonic-core v8.x to v9.0¶

v9.0.0 is a major release, but a narrow one: the breaking change is a dependency-line move, not an API change. symfonic-core now runs on the langgraph 1.x / langchain-core 1.x ecosystem. The public Python API is unchanged — SymfonicAgent, AgentConfig, providers, memory backends, the conversation managers, and the symfonic CLI all behave exactly as on 8.12.

TL;DR — bump your dependency pins to the 1.x line. If you don't pin langchain-core / langgraph directly and you let the extras resolve, a plain pip install -U "symfonic-core[...]>=9.0.0,<10.0" is a drop-in.

Breaking change¶

B1 — requires langgraph 1.x and langchain-core 1.x¶

	v8.x	v9.0
`langgraph`	`>=0.2,<1.0`	`>=1.0,<2.0`
`langchain-core`	`>=0.3,<1.0`	`>=1.0,<2.0`
`langchain-*` providers	0.x line	1.x line
`langgraph-checkpoint-*` (pg/sqlite/mongo)	2.x	3.x / 4.x

Why. The durable checkpoint adapters (langgraph-checkpoint-postgres, -sqlite, and -mongodb) require langgraph-checkpoint>=3, which only ships with langgraph>=1.0. Under 8.12.0's langgraph<1.0 pin, pip install "symfonic-core[mongodb]" was ResolutionImpossible — the durable Mongo checkpointer shipped but could not be installed. v9.0 aligns the whole langchain/langgraph/checkpoint cluster on one consistent line.

Upgrade steps¶

Bump your symfonic-core pin to the 9.x line:

symfonic-core[agent-api,postgres,prompts,anthropic,ask-user]>=9.0.0,<10.0

Raise any direct langchain / langgraph caps. If your project pins these itself (a scaffolded project does — see below), move them to the 1.x line:

langchain-core>=1.0,<2.0
langgraph>=1.0,<2.0        # only if you pin it directly

Provider packages (langchain-anthropic, langchain-openai, …) move to their 1.x releases automatically when you let the symfonic-core extras resolve them — you rarely need to pin them by hand.

Scaffolded projects (symfonic init). The generated requirements.txt pinned symfonic-core[...]>=8.x,<9.0 and langchain-core>=0.3,<1.0. Both caps block 9.0 (and would conflict with each other). Change them to:

symfonic-core[agent-api,postgres,prompts,<provider>,ask-user]>=9.0.0,<10.0
langchain-core>=1.0,<2.0

Projects scaffolded with the 9.0 CLI already ship these pins.

Re-resolve and verify — no version conflicts:

pip install -U -r requirements.txt
pip check          # must print: No broken requirements found

Find stale caps across your codebase¶

grep -rnE "langchain-core[^,]*<1\.0|langgraph[^,]*<1\.0|symfonic-core[^,]*<9(\.0)?\b" .

If nothing matches (and you had no <1.0 langchain/langgraph pins), you're done.

Behavior preserved (no code change required)¶

Tool errors still steer the model (not crash the run)¶

langgraph 1.x flipped its ToolNode default to re-raise non-validation tool exceptions, which would abort a graph run on the first tool that raises. symfonic-core restores the langgraph-0.x contract — a raised tool error becomes a recoverable ToolMessage the model sees and works around — so your agents behave exactly as they did on 8.x. No action needed. (If you want langgraph 1.x's raise-on-error behavior, construct your tool node with an explicit handle_tool_errors=.)

Anthropic `http_client` transport injection¶

The ModelConfig.http_client inter-chunk-idle seam now activates across the langchain-anthropic 1.x line (previously an exact 0.3.x allowlist), guarded by the same structural probe. No change to your code.

Now unblocked¶

Durable MongoDB checkpointer — pip install "symfonic-core[mongodb]" resolves and works. Resumable interactive sessions and durable transcripts survive a restart on Mongo deployments. See Conversation Persistence.

Everything else is additive¶

The 8.12 feature set — conversation managers, the symfonic examples CLI, sub-agents, structured output, the HMS memory system, tenancy, streaming — is unchanged and carried forward with 8.x observable behavior at defaults.

Verifying the upgrade in CI¶

symfonic-core's own CI runs a dependency-resolution gate that dry-runs the full extras matrix and pip checks the durable-checkpointer cluster, so an extra that can't resolve against the core pins fails the build. You can adopt the same guard in your project's CI with two lines:

pip install "symfonic-core[<your-extras>]>=9.0.0,<10.0"
pip check