Honcho Python SDK Migration (v1.6.0 → v2.0.0)

Overview

This skill migrates code from honcho Python SDK v1.6.0 to v2.0.0 (required for Honcho 3.0.0).

Key breaking changes:

•AsyncHoncho/AsyncPeer/AsyncSession removed → use .aio accessor
•"Observation" → "Conclusion" terminology
•Representation class removed (returns str now)
•get_config/set_config → get_configuration/set_configuration
•Streaming via chat_stream() instead of chat(stream=True)
•poll_deriver_status() removed
•.core property removed

Quick Migration

1. Update async architecture

python

# 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

python

# 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

python

# 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

python

# 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

python

# 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

python

# 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)

python

# 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

python

# 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

python

# 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

python

# Before
card: str = peer.card()  # Returns str

# After
card: list[str] | None = peer.card()  # Returns list[str] | None
if card:
    print("\n".join(card))

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()`
`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)

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

python

from honcho import (
    HonchoError,
    APIError,
    BadRequestError,
    AuthenticationError,
    PermissionDeniedError,
    NotFoundError,
    ConflictError,
    UnprocessableEntityError,
    RateLimitError,
    ServerError,
    TimeoutError,
    ConnectionError,
)

New Import Locations

python

# 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