migrate-honcho
Migrates Honcho Python SDK code from v1.6.0 to v2.1.1. Use when upgrading honcho package, fixing breaking changes after upgrade, or when errors mention AsyncHoncho, observations, Representation class, .core property, or get_config methods.
- License 许可
- MIT
- 最近更新
- 2026-10-08
- Stars
- ★ 11
- Forks
- 3
01 前言 Front Matter
- name
- migrate-honcho
- description
- Migrates Honcho Python SDK code from v1.6.0 to v2.1.1. Use when upgrading honcho package, fixing breaking changes after upgrade, or when errors mention AsyncHoncho, observations, Representation class, .core property, or get_config methods.
02 资源文件 2
- 参考文档DETAILED-CHANGES.md13.2 KB
- 参考文档MIGRATION-CHECKLIST.md5.8 KB
03 SKILL.md 正文
Honcho Python SDK Migration (v1.6.0 → v2.1.1)
Overview
This skill migrates code from honcho Python SDK v1.6.0 to v2.1.1 (required for Honcho 3.0.0+).
Key breaking changes:
AsyncHoncho/AsyncPeer/AsyncSessionremoved → use.aioaccessor- "Observation" → "Conclusion" terminology
Representationclass removed (returnsstrnow)get_config/set_config→get_configuration/set_configuration- Streaming via
chat_stream()instead ofchat(stream=True) poll_deriver_status()removed.coreproperty removed
Quick Migration
1. Update async architecture
# Before
from honcho import AsyncHoncho, AsyncPeer, AsyncSession
async_client = AsyncHoncho()
peer = await async_client.peer("user-123")
response = await peer.chat("query")
# After
from honcho import Honcho
client = Honcho()
peer = await client.aio.peer("user-123")
response = await peer.aio.chat("query")
# Async iteration
async for p in client.aio.peers():
print(p.id)
2. Replace observations with conclusions
# Before
from honcho import Observation, ObservationScope, AsyncObservationScope
scope = peer.observations
scope = peer.observations_of("other-peer")
rep = scope.get_representation()
# After
from honcho import Conclusion, ConclusionScope, ConclusionScopeAio
scope = peer.conclusions
scope = peer.conclusions_of("other-peer")
rep = scope.representation() # Returns str
3. Update representation handling
# Before
from honcho import Representation, ExplicitObservation, DeductiveObservation
rep: Representation = peer.working_rep()
print(rep.explicit)
print(rep.deductive)
if rep.is_empty():
print("No observations")
# After
rep: str = peer.representation()
print(rep) # Just a string now
if not rep:
print("No conclusions")
4. Rename configuration methods
# Before
config = peer.get_config()
peer.set_config({"observe_me": False})
session.get_config()
client.get_config()
# After
from honcho.api_types import PeerConfig, SessionConfiguration, WorkspaceConfiguration
config = peer.get_configuration()
peer.set_configuration(PeerConfig(observe_me=False))
session.get_configuration()
client.get_configuration()
5. Update method names
# Before
peer.working_rep()
peer.get_context()
peer.get_sessions()
session.get_context()
session.get_summaries()
session.get_messages()
session.get_peers()
session.get_peer_config()
client.get_peers()
client.get_sessions()
client.get_workspaces()
# After
peer.representation()
peer.context()
peer.sessions()
session.context()
session.summaries()
session.messages()
session.peers()
session.get_peer_configuration()
client.peers()
client.sessions()
client.workspaces()
6. Update streaming
# Before
response = peer.chat("query", stream=True)
for chunk in response:
print(chunk, end="")
# After
stream = peer.chat_stream("query")
for chunk in stream:
print(chunk, end="")
7. Update queue status (formerly deriver)
# Before
from honcho_core.types import DeriverStatus
status = client.get_deriver_status()
status = client.poll_deriver_status(timeout=300.0) # Removed!
# After
from honcho.api_types import QueueStatusResponse
status = client.queue_status()
# poll_deriver_status removed - implement polling manually if needed
8. Update representation parameters
# Before
rep = peer.working_rep(
include_most_derived=True,
max_observations=50
)
# After
rep = peer.representation(
include_most_frequent=True,
max_conclusions=50
)
9. Move update_message to session
# Before
updated = client.update_message(message=msg, metadata={"key": "value"}, session="sess-id")
# After
updated = session.update_message(message=msg, metadata={"key": "value"})
10. Update card() return type and method name
# Before
card: str = peer.card() # Returns str
# After (v2.0.0+)
card: list[str] | None = peer.get_card() # Returns list[str] | None
if card:
print("\n".join(card))
# peer.card() still works but is deprecated — use get_card()
# New in v2.0.1: set_card()
peer.set_card(["Prefers dark mode", "Located in US"])
11. Strict input validation (v2.0.2+)
All input models now reject unknown fields via extra="forbid" Pydantic validation. Previously, misspelled or extraneous fields were silently ignored.
# Before (v2.0.1 and earlier) — silently ignored
peer = client.peer("user-1", configuration=PeerConfig(observe_mee=True)) # typo silently ignored
# After (v2.0.2+) — raises ValidationError
peer = client.peer("user-1", configuration=PeerConfig(observe_mee=True)) # ValidationError!
12. peer() and session() always make API calls (v2.1.0+)
Breaking: peer() and session() now always make a get-or-create API call. Previously, calling without metadata/configuration returned a lazy object with no API call.
# Before (v2.0.x) — no API call without options
peer = client.peer("user-123") # Lazy, no network request
# After (v2.1.0+) — always hits the API
peer = client.peer("user-123") # Makes POST to /peers (get-or-create)
# Async
peer = await client.aio.peer("user-123") # Also always hits API
13. New properties and methods (v2.1.0+)
# created_at on Peer and Session
peer = client.peer("user-123")
print(peer.created_at) # datetime | None
session = client.session("sess-1")
print(session.created_at) # datetime | None
# is_active on Session
print(session.is_active) # bool | None
# get_message() on Session
msg = session.get_message("msg-id")
# Async: msg = await session.aio.get_message("msg-id")
14. Pagination parameters on list methods (v2.1.0+)
All list methods now accept page, size, and reverse parameters:
# Before (v2.0.x) — only filters
peers_page = client.peers(filters={"metadata": {"role": "admin"}})
# After (v2.1.0+) — pagination controls
peers_page = client.peers(
filters={"metadata": {"role": "admin"}},
page=2,
size=25,
reverse=True
)
# Works on: client.peers(), client.sessions(), peer.sessions(),
# session.messages(), scope.list()
15. Broader HTTP retry logic (v2.1.1+)
The SDK now retries on httpx.TimeoutException, httpx.NetworkError, and httpx.RemoteProtocolError (previously only httpx.TimeoutException and httpx.ConnectError). These are mapped to the SDK's TimeoutError and ConnectionError respectively. No code changes needed — this is transparent.
Quick Reference Table
| v1.6.0 | v2.0.0 |
|---|---|
AsyncHoncho() |
Honcho() + .aio accessor |
AsyncPeer |
Peer + .aio accessor |
AsyncSession |
Session + .aio accessor |
Observation |
Conclusion |
ObservationScope |
ConclusionScope |
AsyncObservationScope |
ConclusionScopeAio |
Representation |
str |
.observations |
.conclusions |
.observations_of() |
.conclusions_of() |
.get_config() |
.get_configuration() |
.set_config() |
.set_configuration() |
.working_rep() |
.representation() |
.get_context() |
.context() |
.get_sessions() |
.sessions() |
.get_peers() |
.peers() |
.get_messages() |
.messages() |
.get_summaries() |
.summaries() |
.get_deriver_status() |
.queue_status() |
.poll_deriver_status() |
(removed) |
.get_peer_config() |
.get_peer_configuration() |
.set_peer_config() |
.set_peer_configuration() |
client.update_message() |
session.update_message() |
peer.card() |
peer.get_card() (card() deprecated) |
| (new) | peer.set_card(list[str]) |
chat(stream=True) |
chat_stream() |
include_most_derived= |
include_most_frequent= |
max_observations= |
max_conclusions= |
last_user_message= |
search_query= |
config= |
configuration= |
PeerContext |
PeerContextResponse |
DeriverStatus |
QueueStatusResponse |
client.core |
(removed) |
| (new v2.1.0) | peer.created_at / session.created_at |
| (new v2.1.0) | session.is_active |
| (new v2.1.0) | session.get_message(id) |
| (new v2.1.0) | page=, size=, reverse= on list methods |
Detailed Reference
For comprehensive details on each change, see:
- DETAILED-CHANGES.md - Full API change documentation
- MIGRATION-CHECKLIST.md - Step-by-step checklist
New Exception Types
from honcho import (
HonchoError,
APIError,
BadRequestError,
AuthenticationError,
PermissionDeniedError,
NotFoundError,
ConflictError,
UnprocessableEntityError,
RateLimitError,
ServerError,
TimeoutError,
ConnectionError,
)
New Import Locations
# Configuration types
from honcho.api_types import (
PeerConfig,
SessionConfiguration,
WorkspaceConfiguration,
SessionPeerConfig,
QueueStatusResponse,
PeerContextResponse,
)
# Async type hints
from honcho import HonchoAio, PeerAio, SessionAio
# Message types (note: Params is plural now)
from honcho import Message, MessageCreateParams
04 同仓库更多 Skills
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
python-api
Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP/mAP semantics, and source-style import diagnostics.
file-evaluation
Folder-based PASCAL VOC AP/mAP evaluation from ground-truth and detection text files.
object-detection-metrics
Guides legacy Object-Detection-Metrics PASCAL VOC AP/mAP evaluation from detection text folders and direct Python API classes.
nx-workspace-patterns
Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.