All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
honcho.dreams()andhoncho.get_dream()(sync and async) read Representation History: the dream runs over a workspace's representations, newest first and filterable byobservedandobserver, and one run's created conclusions with their sources, removed conclusions, and peer-card change.pruned_atmarks a run that retention cut down to the created conclusions that still exist. New response typesDreamRunResponseandDreamRunDetailResponse. Requires Honcho v3.6.0+ (#1542)
honcho.sessions()takesscope,in_no_scopeandinclude_scopes(sync and async).scopelists only that scope's sessions,in_no_scope=Trueonly sessions in no scope, andinclude_scopes=TruesetsSession.scopes(andSessionResponse.scopes) to the names of the scopes each listed session is in. Requires Honcho v3.5.0+ (#1477)honcho.scopes()takesfilters(e.g.{"id": {"icontains": "sup"}}, matching the scope name) andinclude_session_count(sync and async). Withinclude_session_count=True,Scope.session_count(andScopeResponse.session_count) holds each listed scope's member session count. Requires Honcho v3.5.0+ (#1478)Scope.remove_sessions()(sync and async) removes up to 100 sessions from a scope in one request. All-or-nothing if any session doesn't exist; sessions that aren't members are ignored. Requires Honcho v3.5.0+ (#1480)Conclusion.source_message_ids: the messages the deriver cited as evidence for an explicit conclusion (Honcho v3.5.0+). None for derived levels, and for conclusions recorded before citations existed until a later derivation of the same conclusion merges citations into them. Filter with{"source_message_ids": {"contains": "<message_id>"}}to find the conclusions that cite a message as evidence (#935)
set_configuration()on the client replaces the whole workspace configuration (Honcho v3.5.0+), soset_configuration(WorkspaceConfiguration())clears explicit settings and uses system defaults; settings left out are removed.refresh()on the client reloads its typed configuration along with metadata (#1458)
- Requires
certifi2026.10.19 or newer, the first CA bundle without the emSign root behind the compromised eMudhra intermediates. The client verifies TLS with httpx's default, which reads certifi, so upgrading the SDK now upgrades the bundle in the app's environment too. An app that pins an oldercertifimust raise that pin to upgrade (#1453)
uidonPeer,Sessionand theHonchoclient (the workspace), plus onPeerResponse,SessionResponseandWorkspaceResponse: the immutable identifier the server assigns, next to the client-chosenid. Set from any API response that returns the object, andNonebefore the first fetch or against servers that don't return it (#1394)
- The async client (
.aio) builds a newhttpx.AsyncClientwhen the running event loop changes, instead of reusing the first loop's client on every later loop. AHonchokept acrossasyncio.run()calls (a module-level client in a Lambda handler, a sync view or a CLI) no longer fails its first request on a new loop withConnectionError: Event loop is closedwhen the previous loop left a pooled connection, sometimes after the write had been stored. A client set directly on_async_httpis still used as is, and each thread running its own loop should use its ownHoncho(#1357)
custom_instructionsonWorkspaceConfigurationandSessionConfiguration(the shared fallback) and onSummaryConfiguration,DreamConfiguration, andPeerCardConfiguration, plus a newDialecticConfigurationtype under thedialectickey. Requires Honcho v3.3.0+ (#1303)
observer_idandobserved_idonEvidenceObservation, so evidence from workspace chat says which peer pair each conclusion belongs to. Previously the SDK dropped these fields. Requires Honcho v3.2.1+ (#1220)
Conclusion.source_idsis[]rather thanNonefor explicit conclusions when talking to Honcho v3.2.1+. The type still admitsNonefor older servers (#1193)
honcho.get_scope(id)(sync and async) fetches an existing scope by ID and raisesNotFoundErrorwhen it does not exist. Unlikehoncho.scope(), it never creates the scope, so lookups cannot provision a recall boundary by accident (#1163)- Optional per-call
timeouton synchronous and asynchronousPeer.chat(). It overrides the timeout for each HTTP attempt; when omitted or set toNone, the client-wide timeout configured onHonchoremains in effect (#1098) include_evidenceon peer and workspace chat (sync, async, and streaming). Opting in returns aChatResponsecarrying the answer plus the conclusions, messages, and tool calls the dialectic read; leaving it out returns the answer on its own, so existing callers are unaffected. Streaming exposes.evidenceonce the stream is drained. Requires a Honcho server with the matching API support (Honcho v3.2.0+) (#1130)source_idsandtimes_derivedonConclusion.ConclusionsView.get(id)/get_many(ids)/derived(id)and the workspace-levelhoncho.conclusions.get/get_manyfetch a conclusion with attribution or walk the reasoning tree upward (source → derived). Requires a Honcho server with the matching API support (Honcho v3.2.0+) (#952)- SDK requests send
X-Honcho-Host: honcho-python/<version> (platform)so CloudEvents can split harness vs direct SDK vs raw REST traffic. A caller-suppliedX-Honcho-Hoststill wins (#1182)
- Scopes:
Honcho.scope()/HonchoAio.scope()get-or-create a named visibility boundary,Honcho.scopes()lists them, and aScopeobject adds/removes sessions, lists membership, and reads backfillstatus().Honcho.session(..., scopes=[...])joins a new session to scopes at creation. Requires a Honcho server with the matching API support (Honcho v3.1.0+). scopeoption onPeer.chat()/chat_stream(), representation, session context, and workspace search. A single scope answers from that scope's collection and card; a list of scopes restricts recall to the union of their member sessions (explicit-only). Mutually exclusive withsession/sessions/filters.- Workspace-level chat:
Honcho.chat()/HonchoAio.chat()andchat_stream()ask a question across every peer in the workspace, with the samesession,scope,reasoning_level, andresponse_formatoptions asPeer.chat(). Requires a Honcho server with the matching API support (Honcho v3.1.0+).
ConclusionScopeis renamed toConclusionsView. The old name remains as a deprecated alias for one more minor version. "Scope" now means a named set of sessions (Scope); these objects are views over one observer/observed pair.
response_formatonPeer.chat()/PeerAio.chat()andPeer.chat_stream()/PeerAio.chat_stream(), for constraining a dialectic answer to a schema. Pass a Pydantic model class to get a validated instance back (parsed viamodel_validate_json), or a raw JSON Schema dict to get the JSON string as-is. Overloads type the return precisely, so a model class narrows to that model and a dict narrows tostr. On the streaming variants, chunks stay raw text that accumulates to a JSON string — parse it after the stream completes. Requires a Honcho server with the matching API support (Honcho v3.0.12+).response_formatfield onDialecticParams.
ConclusionLeveltype (explicit,deductive,inductive,contradiction) and alevelfield onConclusion, exposing the reasoning level the server already tracked but previously stripped from responses.filtersparameter onConclusionScope.list()andConclusionScope.query()(sync and async), passed through to the same dynamic server-side filter logic aspeers()/sessions()/messages(). Filter explicit-only conclusions withfilters={"level": "explicit"}, or by any other supported field/operator. Requires a Honcho server with the matching API support (Honcho v3.0.11+).
- Scope-managed filter keys (
observer,observed,session) are now rejected with a clearValueErrorif passed infilters, instead of silently overriding the scope and returning conclusions from a different peer pair. Usepeer.conclusions/conclusions_of(target)and thesession=parameter instead.session_idremains a valid filter onquery().
page,size, andreversepagination parameters onHoncho.workspaces()andHonchoAio.workspaces(), closing the gap from 2.1.0 which added these topeers(),sessions(),messages(), andconclusions.list()but not toworkspaces(). Honoringreverseon the workspace/peer/session list routes also requires a Honcho server with the matching API fix; older servers silently ignore the parameter.peersparameter onHoncho.session()andHonchoAio.session()— attach peers to a session at creation time instead of needing a follow-upsession.add_peers()call. Accepts the same shapes asSession.add_peers(peer ID string,Peerobject, list of either, or tuples withSessionPeerConfig).
WorkspaceCreateParams,PeerCreateParams, andSessionCreateParamsnow accept IDs up to 512 characters (was 100), matching the server-side schema change in Honcho v3.0.7.
- Broadened HTTP retry logic to cover
httpx.NetworkErrorandhttpx.RemoteProtocolErrorin addition tohttpx.TimeoutExceptionandhttpx.ConnectError, improving resilience against transient network failures
created_atproperty onPeerandSessionobjectsis_activeproperty onSessionobjectsget_message(message_id)method onSession(sync and async) to fetch a single message by IDpage,size, andreversepagination parameters on all list methods:peers(),sessions(),messages(), andconclusions.list()
- Breaking:
peer()andsession()now always make a get-or-create API call. Previously, calling without metadata/configuration returned a lazy object with no API call. All Peer/Session objects now havecreated_atpopulated immediately. - Response configuration models (
WorkspaceConfigurationResponse,SessionConfigurationResponse) now tolerate unknown fields from newer servers for forward compatibility
- Sync and async
Session.get_metadata(),get_configuration(), andrefresh()now refresh cachedcreated_atandis_activevalues along with metadata and configuration. honcho.__version__now derives from package metadata, with apyproject.tomlfallback in source checkouts, so it stays aligned with SDK releases.
- All input models now reject unknown fields via
extra="forbid"Pydantic validation. Previously, misspelled or extraneous fields were silently ignored. Now aValidationErroris raised with the unrecognized field name.
set_peer_cardmethod
cardis nowget_cardwithcardkept for backwards compatibility and marked as deprecated
ConclusionScopeobject for CRUD operations on conclusions (renamed from observations)- Representation configuration support
- Observations renamed to Conclusions across the SDK
- Major SDK refactoring and cleanup
- Simplified method signatures throughout
- Representation endpoints now return
stringinstead of old Representation object
- Standalone types module (now uses honcho-core types)
- Representation object
- metadata and configuration fields to Workspace, Peer, Session, and Message objects
- Session Clone methods
- Peer level get_context method
ObservationScopeobject to perform CRUD operations on observations- Representation object for WorkingRepresentations
- methods that take IDs, can all optionally take an object of the same type
- Delete workspace method
- message_id of
Summarymodel is a string nanoid - Get Context can return Peer Card & Peer Representation
- Get Peer Card method
- Update Message metadata method
- Session level deriver status methods
- Delete session message
- Dialectic Stream returns Iterators
- Type warnings
- Pagination class to match core implementation
- getSummaries API returning structured summaries
- Webhook support
- Messages can take an optional
created_atvalue, defaulting to the current time (UTC ISO 8601)
- Added get_peer_config to sessions module
- Summaries are now included in
toOpenAIandtoAnthropicfunctions SessionContext.__len__now counts the summary in its totalfilterkeyword changed tofilters
- Added missing metadata inputs in many places
- Better documentation all over
- Filter parameter to various endpoints
- honcho utils import path
- Get/poll deriver queue status endpoints added to workspace
- Added endpoint to upload files as messages
- Removed peer messages in accordance with Honcho 2.1.0
- Updated chat endpoint to use singular
queryin accordance with Honcho 2.1.0
- Properly handle AsyncClient