Migrate Honcho

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/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

# 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

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

Detailed API Changes

1. Async Client Architecture (Major Change)

The separate AsyncHoncho, AsyncPeer, and AsyncSession classes have been removed. Use the .aio accessor instead.

Before (v1.6.0)

from honcho import Honcho, AsyncHoncho, AsyncPeer, AsyncSession

# Sync client
client = Honcho()

# Async client - separate class
async_client = AsyncHoncho()
peer = await async_client.peer("user-123")
response = await peer.chat("query")

After (v2.0.0)

from honcho import Honcho

# Single client with .aio accessor for async operations
client = Honcho()

# Sync operations
peer = client.peer("user-123")
response = peer.chat("query")

# Async operations via .aio accessor
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)

Migration steps:

1. Remove all AsyncHoncho, AsyncPeer, AsyncSession imports 2. Replace AsyncHoncho() with Honcho() and use .aio accessor 3. Replace AsyncPeer type hints with Peer 4. Replace AsyncSession type hints with Session 5. Access async methods via .aio property on instances

---

2. Observations → Conclusions (Terminology Change)

Before (v1.6.0)

from honcho import Observation, ObservationScope, AsyncObservationScope

# Access observations
scope = peer.observations
scope = peer.observations_of("other-peer")

# List observations
obs_list = scope.list()

# Query observations
results = scope.query("preferences")

# Create observations
scope.create([{"content": "User likes dark mode", "session_id": "sess-1"}])

# Get representation from observations
rep = scope.get_representation()

After (v2.0.0)

from honcho import Conclusion, ConclusionScope, ConclusionScopeAio

# Access conclusions
scope = peer.conclusions
scope = peer.conclusions_of("other-peer")

# List conclusions (now returns SyncPage, not list)
conclusions_page = scope.list()
for conclusion in conclusions_page:
    print(conclusion.content)

# Query conclusions
results = scope.query("preferences")

# Create conclusions
scope.create([{"content": "User likes dark mode", "session_id": "sess-1"}])

# Get representation from conclusions
rep = scope.representation()  # Returns str, not Representation object

---

3. Representation Type Change (Major Change)

The Representation class has been removed. Representations are now simple strings.

Before (v1.6.0)

from honcho import Representation, ExplicitObservation, DeductiveObservation

# Get working representation
rep: Representation = peer.working_rep()

# Access explicit and deductive observations
for obs in rep.explicit:
    print(obs.content, obs.created_at)

for obs in rep.deductive:
    print(obs.conclusion, obs.premises)

# Check if empty
if rep.is_empty():
    print("No observations")

# Merge representations
rep.merge_representation(other_rep)

# Diff representations
diff = rep.diff_representation(other_rep)

# String formatting
print(str(rep))
print(rep.str_no_timestamps())
print(rep.format_as_markdown())

After (v2.0.0)

# Get representation - now returns str directly
rep: str = peer.representation()

# It's just a string now
print(rep)

# Check if empty
if not rep:
    print("No conclusions")

Removed methods:

• .explicit property
• .deductive property
• .is_empty()
• .merge_representation()
• .diff_representation()
• .str_no_timestamps()
• .format_as_markdown()

---

4. Configuration Parameter Rename

All config parameters have been renamed to configuration, and configuration types are now strongly typed.

Before (v1.6.0)

# Creating resources with config
peer = client.peer("user-1", config={"observe_me": True})
session = client.session("sess-1", config={"some_setting": True})

# Getting/setting config
config = peer.get_config()
peer.set_config({"observe_me": False})

config = session.get_config()
session.set_config({"some_setting": False})

config = client.get_config()
client.set_config({"workspace_setting": True})

# Message config parameter
msg = peer.message("Hello", config={"reasoning": {"enabled": True}})

After (v2.0.0)

from honcho.api_types import PeerConfig, SessionConfiguration, WorkspaceConfiguration

# Creating resources with configuration (typed)
peer = client.peer("user-1", configuration=PeerConfig(observe_me=True))
session = client.session("sess-1", configuration=SessionConfiguration())

# Getting/setting configuration (returns typed objects)
config: PeerConfig = peer.get_configuration()
peer.set_configuration(PeerConfig(observe_me=False))

config: SessionConfiguration = session.get_configuration()
session.set_configuration(SessionConfiguration())

config: WorkspaceConfiguration = client.get_configuration()
client.set_configuration(WorkspaceConfiguration())

# Message configuration parameter
msg = peer.message("Hello", configuration={"reasoning": {"enabled": True}})

---

5. Streaming Chat API Change

Before (v1.6.0)

# Streaming via parameter
response = peer.chat("query", stream=True)
for chunk in response:
    print(chunk, end="")

final = response.get_final_response()

After (v2.0.0)

# Streaming via separate method
stream = peer.chat_stream("query")
for chunk in stream:
    print(chunk, end="")

final = stream.get_final_response()

# Non-streaming (no stream parameter needed)
response = peer.chat("query")

---

6. Deriver Status → Queue Status

Before (v1.6.0)

from honcho_core.types import DeriverStatus

# Get status
status: DeriverStatus = client.get_deriver_status()
status = session.get_deriver_status()

# Poll until complete
status = client.poll_deriver_status(timeout=300.0)
status = session.poll_deriver_status(timeout=300.0)

# Access fields
print(status.pending_work_units)
print(status.in_progress_work_units)

After (v2.0.0)

from honcho.api_types import QueueStatusResponse

# Get status
status: QueueStatusResponse = client.queue_status()
status = session.queue_status()

# Access fields (same as before)
print(status.pending_work_units)
print(status.in_progress_work_units)

# poll_deriver_status has been removed - implement polling manually if needed:
import time

def poll_until_complete(client, timeout=300.0):
    start = time.time()
    while time.time() - start < timeout:
        status = client.queue_status()
        if status.pending_work_units == 0 and status.in_progress_work_units == 0:
            return status
        time.sleep(1)
    raise TimeoutError("Queue processing did not complete in time")

---

7. PeerContext Changes

Before (v1.6.0)

from honcho import PeerContext

context: PeerContext = peer.get_context()

# Access representation (was Representation object)
rep: Representation = context.representation
if rep:
    print(rep.explicit)
    print(rep.deductive)

After (v2.0.0)

from honcho.api_types import PeerContextResponse

context: PeerContextResponse = peer.context()

# Access representation (now str)
rep: str | None = context.representation
if rep:
    print(rep)

---

8. Card Method Return Type Change

Before (v1.6.0)

# card() returned str (joined with newlines)
card: str = peer.card()
print(card)  # "line1\nline2\nline3"

After (v2.0.0)

# card() returns list[str] | None
card: list[str] | None = peer.card()
if card:
    print("\n".join(card))  # Join manually if needed

---

9. Message Update Location Change

Before (v1.6.0)

# Update message via client
updated = client.update_message(
    message=msg,
    metadata={"key": "value"},
    session="session-id"  # Required if message is string ID
)

After (v2.0.0)

# Update message via session
updated = session.update_message(
    message=msg,
    metadata={"key": "value"}
)

---

10. Removed: core Property

Before (v1.6.0)

# Access underlying Stainless-generated client
core_client = client.core
workspace = client.core.workspaces.get_or_create(id="custom-workspace")

After (v2.0.0)

# The `core` property has been removed
# The SDK no longer uses a Stainless-generated client internally
# Use the SDK's public API directly

---

11. Environment Changes

Before (v1.6.0)

# Three environments available
client = Honcho(environment="local")
client = Honcho(environment="production")
client = Honcho(environment="demo")

After (v2.0.0)

# Only two environments
client = Honcho(environment="local")
client = Honcho(environment="production")
# "demo" environment has been removed

---

12. Reasoning Level Parameter (New Feature)

The chat method now supports a reasoning_level parameter:

# New in v2.0.0
response = peer.chat(
    "complex query",
    reasoning_level="high"  # "minimal", "low", "medium", "high", "max"
)

stream = peer.chat_stream(
    "complex query",
    reasoning_level="max"
)

---

13. Import Changes Summary

Removed Imports

# These no longer exist in v2.0.0
from honcho import AsyncHoncho          # Use Honcho with .aio accessor
from honcho import AsyncPeer            # Use Peer with .aio accessor
from honcho import AsyncSession         # Use Session with .aio accessor
from honcho import Observation          # Renamed to Conclusion
from honcho import ObservationScope     # Renamed to ConclusionScope
from honcho import AsyncObservationScope # Renamed to ConclusionScopeAio
from honcho import Representation       # Removed (now str)
from honcho import ExplicitObservation  # Removed
from honcho import DeductiveObservation # Removed
from honcho import PeerContext          # Use PeerContextResponse from api_types

New Imports

from honcho import Conclusion, ConclusionScope
from honcho import ConclusionScopeAio
from honcho import HonchoAio, PeerAio, SessionAio  # For type hints
from honcho import MessageCreateParams, Message

# Typed configuration classes
from honcho.api_types import (
    PeerConfig,
    SessionConfiguration,
    WorkspaceConfiguration,
    SessionPeerConfig,
    QueueStatusResponse,
    PeerContextResponse,
)

Message Type Import Changes

# Before
from honcho_core.types.workspaces.sessions import MessageCreateParam
from honcho_core.types.workspaces.sessions.message import Message
from honcho.session import SessionPeerConfig

# After
from honcho import Message, MessageCreateParams  # Note: plural "Params"
from honcho.api_types import SessionPeerConfig

Note: MessageCreateParam (singular) is now MessageCreateParams (plural).

---

14. Card Method Deprecation and set_card (v2.0.1)

Before (v2.0.0)

card: list[str] | None = peer.card()

After (v2.0.1+)

# get_card() is the preferred method
card: list[str] | None = peer.get_card()

# card() still works but emits a deprecation warning
card = peer.card()  # Deprecated

# New: set_card()
updated = peer.set_card(["Fact 1", "Fact 2"])
updated = peer.set_card(["Fact 1"], target="other-peer")

# Async variants
card = await peer.aio.get_card()
await peer.aio.set_card(["Fact 1"])

---

15. Strict Input Validation (v2.0.2)

All Pydantic input models now use extra="forbid", raising ValidationError for unknown fields.

from honcho.api_types import PeerConfig

# This now raises ValidationError instead of silently ignoring the typo
PeerConfig(observe_mee=True)  # ValidationError: extra fields not permitted

---

16. peer() and session() Always Make API Calls (v2.1.0)

Before (v2.0.x)

# Without options: lazy object, no API call
peer = client.peer("user-123")
# peer.created_at was None

# With options: made API call
peer = client.peer("user-123", metadata={"key": "value"})

After (v2.1.0+)

# Always makes a get-or-create API call
peer = client.peer("user-123")
# peer.created_at is now always populated

# Async
peer = await client.aio.peer("user-123")

All Peer/Session objects now have created_at populated immediately after construction.

---

17. New Properties: created_at, is_active (v2.1.0)

# Peer
peer = client.peer("user-123")
print(peer.created_at)  # datetime | None

# Session
session = client.session("sess-1")
print(session.created_at)  # datetime | None
print(session.is_active)   # bool | None

# These are refreshed by get_metadata(), get_configuration(), and refresh()
peer.refresh()
session.refresh()

---

18. get_message() on Session (v2.1.0)

# Fetch a single message by ID
msg = session.get_message("msg-abc123")
print(msg.content, msg.created_at)

# Async
msg = await session.aio.get_message("msg-abc123")

---

19. Pagination Parameters (v2.1.0)

All list methods now accept page, size, and reverse:

# Defaults: page=1, size=50, reverse=False
peers_page = client.peers(page=2, size=25, reverse=True)

# Returns SyncPage / AsyncPage with:
print(peers_page.total)        # Total items
print(peers_page.pages)        # Total pages
print(peers_page.has_next_page())

# Works on:
# client.peers(), client.sessions()
# peer.sessions()
# session.messages()
# scope.list()

---

20. Broader HTTP Retry Logic (v2.1.1)

The SDK now catches httpx.NetworkError and httpx.RemoteProtocolError for retry in addition to httpx.TimeoutException and httpx.ConnectError. This is transparent — no code changes needed.

Migration Checklist

Use this checklist to track migration progress. Copy into your working notes and check off items as completed.

Dependencies

• [ ] Update honcho package to v2.1.1
• [ ] Remove any honcho-core imports

Async Architecture Changes

• [ ] Remove AsyncHoncho imports → use Honcho with .aio accessor
• [ ] Remove AsyncPeer imports → use Peer with .aio accessor
• [ ] Remove AsyncSession imports → use Session with .aio accessor
• [ ] Update all async client usage to use .aio accessor pattern
• [ ] Update type hints: AsyncPeer → Peer, AsyncSession → Session

Terminology: Observations → Conclusions

• [ ] Replace Observation import with Conclusion
• [ ] Replace ObservationScope import with ConclusionScope
• [ ] Replace AsyncObservationScope import with ConclusionScopeAio
• [ ] Replace .observations property with .conclusions
• [ ] Replace .observations_of() method with .conclusions_of()
• [ ] Replace .get_representation() with .representation()

Representation Changes

• [ ] Remove Representation import (now returns str)
• [ ] Remove ExplicitObservation import
• [ ] Remove DeductiveObservation import
• [ ] Replace working_rep() with representation()
• [ ] Update type hints from Representation to str
• [ ] Remove .explicit property access
• [ ] Remove .deductive property access
• [ ] Replace .is_empty() checks with not rep
• [ ] Remove .merge_representation() calls
• [ ] Remove .diff_representation() calls
• [ ] Remove .str_no_timestamps() calls
• [ ] Remove .format_as_markdown() calls

Configuration Changes

• [ ] Replace all config= parameters with configuration=
• [ ] Replace .get_config() with .get_configuration()
• [ ] Replace .set_config() with .set_configuration()
• [ ] Rename .get_peer_config() → .get_peer_configuration()
• [ ] Rename .set_peer_config() → .set_peer_configuration()
• [ ] Import typed config classes from honcho.api_types if needed:
• [ ] PeerConfig
• [ ] SessionConfiguration
• [ ] WorkspaceConfiguration

Method Renames

Peer Methods

• [ ] peer.working_rep() → peer.representation()
• [ ] peer.get_context() → peer.context()
• [ ] peer.get_sessions() → peer.sessions()
• [ ] peer.chat(stream=True) → peer.chat_stream()

Session Methods

• [ ] session.get_context() → session.context()
• [ ] session.get_summaries() → session.summaries()
• [ ] session.get_messages() → session.messages()
• [ ] session.get_peers() → session.peers()
• [ ] session.get_peer_config() → session.get_peer_configuration()
• [ ] session.set_peer_config() → session.set_peer_configuration()
• [ ] session.working_rep() → session.representation()
• [ ] session.get_deriver_status() → session.queue_status()
• [ ] Remove session.poll_deriver_status() calls

Client Methods

• [ ] client.get_peers() → client.peers()
• [ ] client.get_sessions() → client.sessions()
• [ ] client.get_workspaces() → client.workspaces()
• [ ] client.get_deriver_status() → client.queue_status()
• [ ] Remove client.poll_deriver_status() calls
• [ ] Move client.update_message() → session.update_message()

Parameter Renames

• [ ] include_most_derived= → include_most_frequent=
• [ ] max_observations= → max_conclusions=
• [ ] last_user_message= → search_query=

Return Type Changes

• [ ] Handle card() returning list[str] | None instead of str
• [ ] Handle .list() on conclusions returning SyncPage instead of list

Removed Features

• [ ] Remove any usage of client.core property
• [ ] Remove usage of "demo" environment (only "local" and "production" remain)
• [ ] Implement custom polling if you were using poll_deriver_status()

Type Import Updates

• [ ] Replace PeerContext import with PeerContextResponse from honcho.api_types
• [ ] Replace DeriverStatus import with QueueStatusResponse from honcho.api_types
• [ ] Replace MessageCreateParam with MessageCreateParams (plural)
• [ ] Move SessionPeerConfig import from honcho.session to honcho.api_types

Exception Handling (Optional)

• [ ] Update exception handling to use new exception types if needed:
• HonchoError, APIError, BadRequestError, AuthenticationError
• PermissionDeniedError, NotFoundError, ConflictError
• UnprocessableEntityError, RateLimitError, ServerError
• TimeoutError, ConnectionError

Card Method Updates (v2.0.1)

• [ ] Replace peer.card() with peer.get_card() (card() is deprecated)
• [ ] Use peer.set_card(list[str]) if setting peer cards

Strict Validation (v2.0.2)

• [ ] Verify no input models pass unknown/misspelled fields (now raises ValidationError)
• [ ] Check for typos in PeerConfig, SessionConfiguration, WorkspaceConfiguration fields

peer() / session() API Call Change (v2.1.0)

• [ ] Update code that relied on lazy peer() / session() — they now always make API calls
• [ ] Add await if using async and previously didn't need it for lazy construction

New Properties (v2.1.0)

• [ ] Use peer.created_at / session.created_at where creation time is needed
• [ ] Use session.is_active where session active status is needed

New Methods (v2.1.0)

• [ ] Use session.get_message(message_id) to fetch single messages by ID

Pagination Parameters (v2.1.0)

• [ ] Add page, size, reverse parameters to list calls where needed:
• [ ] client.peers()
• [ ] client.sessions()
• [ ] peer.sessions()
• [ ] session.messages()
• [ ] scope.list()

Final Verification

• [ ] Run type checker (mypy/pyright) with no errors
• [ ] Run tests
• [ ] Verify async operations work with .aio accessor
• [ ] Verify streaming functionality works with chat_stream()
• [ ] Verify configuration changes take effect