migrate-honcho

Honcho Python SDK の移行（v1.6.0 → v2.1.1）

概要

このスキルは、Honcho 3.0.0 以降で必須となる honcho Python SDK v1.6.0 から v2.1.1 へのコード移行を行います。

主な破壊的変更：

• AsyncHoncho／AsyncPeer／AsyncSession が削除されました → .aio アクセサーを使用してください
• 「Observation」から「Conclusion」へ用語を変更
• Representation クラスが削除されました（現在は str を返します）
• get_config／set_config から get_configuration／set_configuration へ変更
• chat(stream=True) ではなく chat_stream() でストリーミング
• poll_deriver_status() が削除されました
• .core プロパティが削除されました

クイック移行ガイド

1. 非同期アーキテクチャを更新する

# 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. observations を 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. representation の処理を更新する

# 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. 設定メソッドの名前を変更する

# 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. メソッド名を更新する

# 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. ストリーミングを更新する

# 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. キューのステータスを更新する（以前の 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. representation のパラメーターを更新する

# Before
rep = peer.working_rep(
    include_most_derived=True,
    max_observations=50
)

# After
rep = peer.representation(
    include_most_frequent=True,
    max_conclusions=50
)

9. update_message を 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. card() の戻り値の型とメソッド名を更新する

# 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. 入力の厳密な検証（v2.0.2 以降）

すべての入力モデルで、Pydantic の検証により extra="forbid" を使って未知のフィールドを拒否するようになりました。以前は、スペルミスのあるフィールドや余分なフィールドは警告なしに無視されていました。

# 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() と session() は常に API 呼び出しを行う（v2.1.0 以降）

破壊的変更：peer() と session() は常に get-or-create API 呼び出しを行うようになりました。以前は、メタデータや設定を指定せずに呼び出すと、API 呼び出しを行わない遅延オブジェクトが返されていました。

# 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. 新しいプロパティとメソッド（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. list メソッドのページネーションパラメーター（v2.1.0 以降）

すべての list メソッドで page、size、reverse パラメーターを指定できるようになりました。

# 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. HTTP 再試行ロジックの拡張（v2.1.1 以降）

SDK は httpx.TimeoutException、httpx.NetworkError、httpx.RemoteProtocolError（以前は httpx.TimeoutException と httpx.ConnectError のみ）発生時に再試行するようになりました。これらはそれぞれ、SDK の TimeoutError と ConnectionError にマッピングされます。コードの変更は不要です。これは透過的に行われます。

クイックリファレンステーブル

v1.6.0	v2.0.0
AsyncHoncho()	Honcho() + .aio アクセサー
AsyncPeer	Peer + .aio アクセサー
AsyncSession	Session + .aio アクセサー
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()	(削除)
.get_peer_config()	.get_peer_configuration()
.set_peer_config()	.set_peer_configuration()
client.update_message()	session.update_message()
peer.card()	peer.get_card() (card() は非推奨)
(新規)	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	(削除)
(v2.1.0 で新規)	peer.created_at / session.created_at
(v2.1.0 で新規)	session.is_active
(v2.1.0 で新規)	session.get_message(id)
(v2.1.0 で新規)	list メソッドの page=、size=、reverse=

詳細リファレンス

各変更の詳細については、以下を参照してください。

• DETAILED-CHANGES.md - API 変更の全ドキュメント
• MIGRATION-CHECKLIST.md - 手順ごとのチェックリスト

新しい例外型

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