From 6b7cf82c1c3c87f88fcdc339e1a03a7b499da4be Mon Sep 17 00:00:00 2001 From: Eri Barrett Date: Wed, 27 Aug 2025 12:03:09 -0400 Subject: [PATCH] docs quickfix (#198) * updated platform page * fix: update explore page screenshots * fix: empty object to init client * fix: add async operations to ts code * add: output structure for sessionContext, messages, and workingrep in docs * Delete docs/scratch.md * fix: review comments * fix: delete the 212 version from changelog * Apply stashed changes and resolve conflicts --- .gitignore | 1 + .../documentation/introduction/quickstart.mdx | 17 +- .../documentation/introduction/vibecoding.mdx | 315 ++---------------- docs/v2/documentation/reference/platform.mdx | 60 ++-- docs/v2/guides/search.mdx | 2 +- 5 files changed, 73 insertions(+), 322 deletions(-) diff --git a/.gitignore b/.gitignore index c3374209..cc184613 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ docker-compose.yml compose.yml + # Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] diff --git a/docs/v2/documentation/introduction/quickstart.mdx b/docs/v2/documentation/introduction/quickstart.mdx index 42f36171..c6c8fd92 100644 --- a/docs/v2/documentation/introduction/quickstart.mdx +++ b/docs/v2/documentation/introduction/quickstart.mdx @@ -64,24 +64,14 @@ from honcho import Honcho # Initialize client (uses demo environment and default workspace) client = Honcho() -# Demo environment: create your own workspace using a nanoid or uuid -# otherwise it could be difficult to retrieve your message data via API -client = Honcho( - workspace="your-workspace-id" -) ``` ```typescript TypeScript import { Honcho } from '@honcho-ai/sdk'; -// Initialize client (uses demo environment) +// Initialize client (uses demo environment and default workspace) const client = new Honcho({}); -// Demo environment: create your own workspace using a nanoid or uuid -// otherwise it could be difficult to retrieve your data via API -const client = new Honcho({ - workspace: "your-workspace-id" -}) ``` @@ -89,11 +79,12 @@ const client = new Honcho({ ```python Python +import os from honcho import Honcho # Production environment with API key client = Honcho( - api_key="your-api-key", + api_key=os.environ["HONCHO_API_KEY"], environment="production", # Create a workspace, otherwise set to "default" # workspace="your-workspace-id" @@ -105,7 +96,7 @@ import { Honcho } from '@honcho-ai/sdk'; // Production environment with API key const client = new Honcho({ - apiKey: "your-api-key", + apiKey: process.env.HONCHO_API_KEY!, environment: "production", // Create a workspace, otherwise set to "default" // workspace: "your-workspace-id" diff --git a/docs/v2/documentation/introduction/vibecoding.mdx b/docs/v2/documentation/introduction/vibecoding.mdx index fbd91a6e..beb2f9a9 100644 --- a/docs/v2/documentation/introduction/vibecoding.mdx +++ b/docs/v2/documentation/introduction/vibecoding.mdx @@ -1,296 +1,55 @@ --- -title: "Cursor & Claude: AI-Powered Honcho Setup" +title: "AI-Powered Honcho Setup" icon: "wand-magic-sparkles" -description: "Build Honcho-powered AI agents quickly using Cursor or Claude. Zero configuration required." +description: "Universal starter prompt for building with Honcho" sidebarTitle: 'Vibecoding Setup' --- -Get Honcho up and running in minutes using AI coding assistants. These prompts are specifically optimized for Cursor and Claude to generate production-ready code with minimal effort. +Copy this prompt into Cursor, Claude, or any AI coding assistant to start building with Honcho. -## 🚀 Quickstart - -Choose your path based on your use case: - -### Personal AI Assistant - -Build an AI assistant that remembers conversations and learns user preferences. - - -Copy this prompt into Cursor or Claude to get a complete implementation: - +## 🚀 Universal Starter Prompt ``` -Create a personal AI assistant using Honcho that remembers user preferences and conversations. Requirements: +I want to start building with Honcho - a memory and personalization platform for AI applications. -REFERENCE DOCUMENTATION: -- Honcho Docs: https://docs.honcho.dev -- Honcho GitHub: https://github.com/plastic-labs/honcho -- Python SDK: https://github.com/plastic-labs/honcho-python +## Honcho Resources + +**Documentation:** +- Main docs: https://docs.honcho.dev - API Reference: https://docs.honcho.dev/v2/api-reference/introduction +- Quickstart: https://docs.honcho.dev/v2/documentation/introduction/quickstart +- Architecture: https://docs.honcho.dev/v2/documentation/reference/architecture -WHAT TO BUILD: -- Personal assistant that learns about the user automatically -- Remembers preferences, habits, and conversation history -- Provides personalized responses based on past interactions -- Uses Honcho's demo server (no setup required) - -TECHNICAL SETUP: -- Python with Honcho SDK and OpenAI -- Simple command-line interface for testing -- Environment: Use demo.honcho.dev (no API key needed) -- LLM: OpenAI GPT-4 (provide env var setup) - -CODE REQUIREMENTS: -- Complete working example with extensive comments -- Error handling and user-friendly messages -- Demonstration of key Honcho concepts: - * Creating peers (user and assistant) - * Managing sessions and conversations - * Automatic learning from interactions - * Querying learned information - * Getting context for AI responses - -EXAMPLE WORKFLOW: -1. User starts conversation with assistant -2. Assistant responds using any existing knowledge about user -3. System automatically learns facts from the conversation -4. System stores conversation in session -5. Future conversations reference past interactions - -Include installation instructions, environment setup, and example conversations to test. -``` - -### Discord Bot with Memory - -Create a Discord bot that learns about server members and provides personalized interactions. - -``` -Build a Discord bot using Honcho that learns about server members and provides personalized interactions. - -REFERENCE DOCUMENTATION: -- Honcho Docs: https://docs.honcho.dev -- Honcho GitHub: https://github.com/plastic-labs/honcho +**Code & Examples:** +- Core repo: https://github.com/plastic-labs/honcho - Python SDK: https://github.com/plastic-labs/honcho-python -- Discord Guide: https://docs.honcho.dev/v2/guides/discord -- API Reference: https://docs.honcho.dev/v2/api-reference/introduction +- TypeScript SDK: https://github.com/plastic-labs/honcho-node +- Discord bot starter: https://github.com/plastic-labs/discord-python-starter +- Telegram bot example: https://github.com/plastic-labs/telegram-python-starter -STARTER TEMPLATE: -- Use the official discord-python-starter from Plastic Labs: https://github.com/plastic-labs/discord-python-starter -- This template already includes Honcho integration, py-cord, and fly.io deployment -- Modify the existing bot.py file to add enhanced memory features +**What Honcho Does:** +Honcho provides persistent memory and personalization for AI apps. It automatically: +- Stores conversation history across sessions +- Learns facts about users from conversations +- Builds user representations for personalized responses +- Manages multi-user sessions with theory of mind +- Provides context injection for any LLM -WHAT TO BUILD: -- Discord bot with persistent memory using Honcho -- Learns about users through natural conversation -- Provides personalized responses based on user history -- Handles multi-user conversations with context awareness -- Extends the starter template with advanced memory features +**Architecture Overview:** +- Core primitives: Workspaces contain Peers (users/agents) and Sessions (conversations) +- Peers can observe other peers in sessions (configurable with observe_me_observe_others) +- Background deriver processes messages to extract facts and update representations +- Dialectic API provides personalized responses based on learned context +- Supports any LLM (OpenAI, Anthropic, open source) +- Can use demo server or self-host -TECHNICAL SETUP: -- Clone the discord-python-starter repository -- Python with py-cord, Honcho SDK, and OpenRouter LLM support -- Uses uv for package management (already configured) -- Environment variables template provided (.env.template) -- Docker and fly.io deployment ready +Please assess the resources above and ask me relevant questions to help build a well-structured application using Honcho. Consider asking about: +- What I'm trying to build +- My technical preferences and stack +- Whether I want to use the demo server or self-host +- My experience level with the technologies involved +- Specific features I need (multi-user, voice, web UI, etc.) -CORE FEATURES TO ADD: -- Enhanced per-user memory and personality modeling -- Channel-specific session management -- Theory-of-mind queries ("What does this user like?") -- Advanced fact extraction from conversations -- Multi-participant conversation handling -- Slash commands for memory management - -IMPLEMENTATION REQUIREMENTS: -- Extend the existing on_message function with memory features -- Add new slash commands for memory testing and management -- Integrate Honcho's dialectic API for personalized responses -- Add session management for different channels -- Implement background fact learning and storage -- Error handling and comprehensive logging - -DEPLOYMENT: -- Use the included fly.toml for deployment -- Environment variable management with fly secrets -- Docker containerization (Dockerfile provided) - -Include examples of enhanced bot interactions and memory demonstrations. +Once you understand my needs, help me create a working implementation with proper memory persistence. ``` -## 🎯 Using Cursor - -### Setup Workflow - - - - ```bash - # Create project - mkdir my-honcho-agent - cd my-honcho-agent - - # Open in Cursor - cursor . - - # Use Cmd+L to open AI chat - # Paste one of the prompts above - ``` - - - ```bash - # Clone the starter template - git clone https://github.com/plastic-labs/discord-python-starter.git - cd discord-python-starter - - # Install dependencies - uv sync - - # Configure environment - cp .env.template .env - # Add your Discord token and API keys - ``` - - - -### Cursor Tips - - - - Use `@codebase` to ask questions about your entire project - - - Use `@docs https://docs.honcho.dev` for documentation context - - - Ask Cursor to write comprehensive tests for your Honcho integration - - - Request specific improvements: "Add better error handling" - - - -## 🤖 Claude Workflows - -### Rapid Development - -``` -I want to quickly prototype an AI agent with Honcho. Help me build: - -REFERENCE DOCUMENTATION: -- Honcho Docs: https://docs.honcho.dev -- Honcho GitHub: https://github.com/plastic-labs/honcho -- Quickstart Guide: https://docs.honcho.dev/v2/documentation/introduction/quickstart -- SDK Documentation: https://docs.honcho.dev/v2/documentation/platform/sdk - -1. SETUP: Complete development environment with Honcho demo server -2. CORE: Basic peer/session/message workflow with memory -3. INTEGRATION: OpenAI LLM integration with context management -4. TESTING: Simple test cases to verify memory functionality -5. ITERATION: Framework for adding features incrementally - -Focus on: -- Working code over perfect architecture -- Clear comments explaining Honcho concepts -- Easy-to-modify structure for experimentation -- Immediate feedback and testing capabilities - -Start with the most minimal viable example and show me how to extend it. -``` - -### Production Deployment - -``` -Help me deploy my Honcho application to production: - -REFERENCE DOCUMENTATION: -- Self-Hosting Guide: https://docs.honcho.dev/v2/contributing/self-hosting -- Configuration Guide: https://docs.honcho.dev/v2/contributing/configuration-guide -- Platform Overview: https://docs.honcho.dev/v2/documentation/platform/overview - -REQUIREMENTS: -- Environment configuration and secrets management -- Database setup and migrations -- API authentication and rate limiting -- Monitoring and logging setup -- Deployment automation - -Provide step-by-step deployment instructions for [Fly.io/Vercel/Railway/Heroku]. -``` - -## 💡 Common Patterns - -### Basic Conversation Flow - -1. **Initialize**: Create peers and start a session -2. **Converse**: Exchange messages between user and assistant -3. **Learn**: Honcho automatically extracts facts from conversations -4. **Remember**: Future conversations use accumulated context -5. **Personalize**: Responses adapt based on learned information - -### Advanced Features - - - - Implement separate memory contexts for different users or channels - - - Manage conversation history to stay within LLM token limits - - - Query and update the knowledge graph programmatically - - - Use dialectic API to reason about user preferences and mental states - - - -## 🛠️ Troubleshooting - - -```text Connection Issues -"My Honcho connection is failing with [ERROR]. Here's my environment setup: [paste code]. What's wrong and how do I fix it?" -``` - -```text Memory Not Persisting -"The agent isn't remembering conversations between sessions. Here's my session management code: [paste code]. Help me debug this." -``` - -```text Performance Optimization -"My Honcho queries are slow. Here's my implementation: [paste code]. How can I optimize this?" -``` - -```text Integration Problems -"I'm trying to integrate Honcho with [SYSTEM] but getting [ERROR]. Here's my approach: [paste code]. What's the correct way to do this?" -``` - - -## 🚀 Next Steps - -After your initial setup: - -1. **Add Features**: Extend with voice input, web UI, or API endpoints -2. **Improve Memory**: Implement custom fact extraction and retrieval -3. **Scale Up**: Add caching, background processing, and optimization -4. **Deploy**: Move from demo server to production environment -5. **Monitor**: Add logging, metrics, and error tracking - -## 📚 Resources - -### Documentation -- **Main Docs**: [docs.honcho.dev](https://docs.honcho.dev) -- **API Reference**: [docs.honcho.dev/v2/api-reference](https://docs.honcho.dev/v2/api-reference/introduction) - -### Code & Examples -- **Honcho Core**: [github.com/plastic-labs/honcho](https://github.com/plastic-labs/honcho) -- **Python SDK**: [github.com/plastic-labs/honcho-python](https://github.com/plastic-labs/honcho-python) -- **TypeScript SDK**: [github.com/plastic-labs/honcho-node](https://github.com/plastic-labs/honcho-node) -- **Discord Starter**: [github.com/plastic-labs/discord-python-starter](https://github.com/plastic-labs/discord-python-starter) - -### Key Concepts for AI Prompts -When working with AI assistants, mention these concepts: -- **Core**: "peers, sessions, messages, facts" -- **Advanced**: "dialectic API, theory of mind, context management" -- **Integration**: "LLM context injection, session persistence, multi-user handling" - - -**Pro Tip**: Be specific about your requirements and constraints when prompting AI. The more context you provide, the better the generated code will match your needs. - diff --git a/docs/v2/documentation/reference/platform.mdx b/docs/v2/documentation/reference/platform.mdx index a6657125..7c563df8 100644 --- a/docs/v2/documentation/reference/platform.mdx +++ b/docs/v2/documentation/reference/platform.mdx @@ -16,107 +16,107 @@ and start building with Honcho. ## 1. Go to [app.honcho.dev](https://app.honcho.dev) Create an account to start using Honcho. If a teammate already uses Honcho, ask -them to invite you to their organization; otherwise, you'll see a banner +them to invite you to their organization. Otherwise, you'll see a banner prompting you to create a new one. -Honcho Platform Dashboard +Honcho Platform Dashboard Once you've created an organization, you'll be taken to the dashboard and see the **Get Started** page with integration guidance and links to documentation. -Honcho Dashboard Getting Started +Honcho Dashboard Getting Started Each organization has dedicated infrastructure running to isolate your workloads. Until you activate a subscription under the -[Billing](https://app.honcho.dev/billing) page, the infrastructure will be -deactivated. +[Billing](https://app.honcho.dev/billing) page, the infrastructure will remain +inactive. ## 2. Activate your Honcho instance Navigate to the [Billing](https://app.honcho.dev/billing) page to activate your subscription. Your Honcho instance provisions automatically, and you can monitor the deployment on the [Instance Status](https://app.honcho.dev/status) page until all systems show a green check mark. -Instance Status Page +Instance Status Page You can also upgrade Honcho when new versions are made available directly from the status page. -Upgrade Honcho +Upgrade Honcho The **Performance** page provides comprehensive monitoring with usage metrics, health analytics, API response times, and endpoint usage across Honcho. -Performance Analytics Dashboard +Performance Analytics Dashboard ## 3. Manage API Keys The [API Keys](https://app.honcho.dev/api-keys) page allows you to create and manage authentication tokens for different environments. You can create admin-level keys with full instance access or scope keys to specific `Workspaces`, `Peers`, or `Sessions`. -API Key Management Dashboard +API Key Management Dashboard ## 4. Test with API Playground -The [API Playground](https://app.honcho.dev/playground) provides a Postman-like interface to test queries, explore endpoints, and validate your integration. Send requests directly to your Honcho instance with real-time responses and full request/response logging. +The [API Playground](https://app.honcho.dev/playground) provides a Postman-like interface to test queries, explore endpoints, and validate your integration. Authenticate with an API key and send requests directly to your Honcho instance with real-time responses and full request/response logging. -API Playground Interface +API Playground Interface ## 5. Workspaces The [Explore](https://app.honcho.dev/explore) page provides comprehensive `Workspace` management where you can create workspaces and begin exploring the platform. Each `Workspace` serves as a container for organizing your Honcho data. -Workspace Table +Workspace Table -Click into any workspace to access a general overview of `Peers` and `Sessions`. Here you can quickly create `Peers`, `Sessions`, and add multiple `Peers` to any particular `Session`. Edit the metadata and configuration for a `Workspace` with the Edit Config button. Click into any entity to navigate to their respective utilities pages or click the expand icon to view Workspace-wide `Peers` and `Sessions` data tables with more details. +Click into any workspace to access a general overview of `Peers` and `Sessions`. Here you can quickly create `Peers`, `Sessions`, and add multiple `Peers` to any `Session`. Edit the metadata and configuration for a `Workspace` with the Edit Config button. Click into any entity to navigate to their respective utilities pages or click the expand icon to view Workspace-wide `Peers` and `Sessions` data tables with more details. -Workspace Dashboard Overview +Workspace Dashboard Overview ## 6. Peer Dashboard & Utilities Expand the `Peers` list from the `Workspace` dashboard to see a detailed view of `Peers`. -Peer Dashboard +Peer Dashboard Click into any peer to navigate to their respective utilities page. Next to the `Peer` name you can edit the [Global Peer Configuration](/v2/documentation/core-concepts/configuration), and in the tabs below, explore all utilities for the `Peer`. -Peer Management Dashboard +Peer Management Dashboard Utilities include: -- **Message search** across all sessions for a particular peer -- **Dialectic Chat** to query peer representations globally or session-scoped (results vary dependant on the peer's configuration) +- **Message search** across all sessions for a `Peer` +- **Dialectic Chat** to query `Peer` representations globally or session-scoped (results vary dependant on the `Peer`'s configuration) -Chat Endpoint +Chat Endpoint - **Session logs** view which `Sessions` the `Peer` is active - **Peer configuration and metadata management** including [Session-Peer Configuration](/v2/documentation/core-concepts/configuration#session-peer-configuration) -Peer Management Dashboard +Peer Management Dashboard ## 7. Session Dashboard & Utilities Click into the sessions view within a workspace to see a table of all of your `Sessions` data. -Sessions Table +Sessions Table -Click into a particular `Session` to open its utilities page. +Click into a `Session` to open its utilities page. -Session Utilities +Session Utilities Here you can: -- **View and Add Messages** within the `Session`, filter messages by `Peer` +- **View and add Messages** within the `Session`; filter messages by `Peer` - **Advanced search** across `Session` messages -- **Peer management** for adding and removing `Peers` and editing a `Peer`'s Session-level configuration -- **Get Context** feature for generating LLM-ready context with customizable token limits +- **Peer management** for adding/removing `Peers` and editing a `Peer`'s Session-level configuration +- **Get Context** to generate LLM-ready context with customizable token limits -Get Context +Get Context -## 8. Webhook Integration +## 8. Webhooks Integration The [Webhooks](https://app.honcho.dev/webhooks) page enables Webhook creation and management. -Webhooks Dashboard +Webhooks Dashboard ## 9. Organization Member Access The [Members](https://app.honcho.dev/members) page provides organization administration to manage your team's access to Honcho with the ability to grant admin permissions. -Members Dashboard +Members Dashboard ## Go Further diff --git a/docs/v2/guides/search.mdx b/docs/v2/guides/search.mdx index 23561393..c82b3bd7 100644 --- a/docs/v2/guides/search.mdx +++ b/docs/v2/guides/search.mdx @@ -151,7 +151,7 @@ results = my_peer.search("budget planning", filters={"session_id": my_session.id ``` -The search results return an array of message objects with the following structure: +Search returns an object containing an `items` array of message objects: ```json {