Using Filters

Honcho provides a sophisticated filtering system that allows you to query workspaces, peers, sessions, and messages with precise control. The filtering system supports logical operators, comparison operators, metadata filtering, and wildcards to help you find exactly what you need.

Basic Filtering Concepts

Filters in Honcho are expressed as dictionaries that define conditions for matching resources. The system supports both simple equality filters and complex queries with multiple conditions.

Simple Filters

The most basic filters check for exact matches:

from honcho import Honcho

# Initialize client
honcho = Honcho()

# Simple peer filter
peers = honcho.peers(filters={"peer_id": "alice"})

# Simple session filter with metadata
sessions = honcho.sessions(filters={
    "metadata": {"type": "support"}
})

# Simple message filter
messages = honcho.messages(filters={
    "session_id": "support-chat-1",
    "peer_id": "alice"
})

import { Honcho } from "@honcho-ai/sdk";

(async () => {
    // Initialize client
    const honcho = new Honcho({});

    // Simple peer filter
    const peers = await honcho.peers({
      filters: { peer_id: "alice" }
    });

    // Simple session filter with metadata
    const sessions = await honcho.sessions({
      filters: {
        metadata: { type: "support" }
      }
    });

    // Simple message filter
    const messages = await honcho.messages({
      filters: {
        session_id: "support-chat-1",
        peer_id: "alice"
      }
    });
})();

Logical Operators

Combine multiple conditions using logical operators for complex queries:

AND Operator

Use AND to require all conditions to be true:

messages = honcho.messages(filters={
    "AND": [
        {"session_id": "chat-1"},
        {"created_at": {"gte": "2024-01-01"}}
    ]
})

(async () => {
    const messages = await honcho.messages({
      filters: {
        AND: [
          { session_id: "chat-1" },
          { created_at: { gte: "2024-01-01" } }
        ]
      }
    });
})();

OR Operator

Use OR to match any of the specified conditions:

# Find messages from either alice or bob
messages = session.messages(filters={
    "OR": [
        {"peer_id": "alice"},
        {"peer_id": "bob"}
    ]
})

# Complex OR with metadata conditions
sessions = honcho.sessions(filters={
    "OR": [
        {"metadata": {"priority": "high"}},
        {"metadata": {"urgent": True}},
        {"metadata": {"escalated": True}}
    ]
})

(async () => {
    // Find messages from either alice or bob
    const messages = await session.messages({
      filters: {
        OR: [
          { peer_id: "alice" },
          { peer_id: "bob" }
        ]
      }
    });

    // Complex OR with metadata conditions
    const sessions = await honcho.sessions({
      filters: {
        OR: [
          { metadata: { priority: "high" } },
          { metadata: { urgent: true } },
          { metadata: { escalated: true } }
        ]
      }
    });
})();

NOT Operator

Use NOT to exclude specific conditions:

# Find all peers except alice
peers = honcho.peers(filters={
    "NOT": [
        {"peer_id": "alice"}
    ]
})

# Find sessions that are NOT completed
sessions = honcho.sessions(filters={
    "NOT": [
        {"metadata": {"status": "completed"}}
    ]
})

(async () => {
    // Find all peers except alice
    const peers = await honcho.peers({
      filters: {
        NOT: [
          { peer_id: "alice" }
        ]
      }
    });

    // Find sessions that are NOT completed
    const sessions = await honcho.sessions({
      filters: {
        NOT: [
          { metadata: { status: "completed" } }
        ]
      }
    });
})();

Combining Logical Operators

Create sophisticated queries by combining different logical operators:

# Find messages from alice OR bob, but NOT where message has archived set to true in metadata
messages = session.messages(filters={
    "AND": [
        {
            "OR": [
                {"peer_id": "alice"},
                {"peer_id": "bob"}
            ]
        },
        {
            "NOT": [
                {"metadata": {"archived": True}}
            ]
        }
    ]
})

(async () => {
    // Find messages from alice OR bob, but NOT where message has archived set to true in metadata
    const messages = await session.messages({
      filters: {
        AND: [
          {
            OR: [
              { peer_id: "alice" },
              { peer_id: "bob" }
            ]
          },
          {
            NOT: [
              { metadata: { archived: true } }
            ]
          }
        ]
      }
    });
})();

Comparison Operators

Use comparison operators for range queries and advanced matching:

Numeric Comparisons

# Find sessions created after a specific date
sessions = honcho.sessions(filters={
    "created_at": {"gte": "2024-01-01"}
})

# Find messages within a date range
messages = session.messages(filters={
    "created_at": {
        "gte": "2024-01-01",
        "lte": "2024-12-31"
    }
})

# Metadata numeric comparisons
sessions = honcho.sessions(filters={
    "metadata": {
        "score": {"gt": 8.5},
        "duration": {"lte": 3600}
    }
})

(async () => {
    // Find sessions created after a specific date
    const sessions = await honcho.sessions({
      filters: {
        created_at: { gte: "2024-01-01" }
      }
    });

    // Find messages within a date range
    const messages = await session.messages({
      filters: {
        created_at: {
          gte: "2024-01-01",
          lte: "2024-12-31"
        }
      }
    });

    // Metadata numeric comparisons
    const filteredSessions = await honcho.sessions({
      filters: {
        metadata: {
          score: { gt: 8.5 },
          duration: { lte: 3600 }
        }
      }
    });
})();

List Membership

# Find messages from specific peers in a session
messages = session.messages(filters={
    "peer_id": {"in": ["alice", "bob", "charlie"]}
})

# Find sessions with specific tags
sessions = honcho.sessions(filters={
    "metadata": {
        "tag": {"in": ["important", "urgent", "follow-up"]}
    }
})

# Not equal comparisons
peers = honcho.peers(filters={
    "metadata": {
        "status": {"ne": "inactive"}
    }
})

(async () => {
    // Find messages from specific peers in a session
    const messages = await session.messages({
      filters: {
        peer_id: { in: ["alice", "bob", "charlie"] }
      }
    });

    // Find sessions with specific tags
    const sessions = await honcho.sessions({
      filters: {
        metadata: {
          tag: { in: ["important", "urgent", "follow-up"] }
        }
      }
    });

    // Not equal comparisons
    const peers = await honcho.peers({
      filters: {
        metadata: {
          status: { ne: "inactive" }
        }
      }
    });
})();

Metadata Filtering

Metadata filtering is particularly powerful in Honcho, supporting nested conditions and complex queries:

Basic Metadata Filtering

# Simple metadata equality
sessions = honcho.sessions(filters={
    "metadata": {
        "type": "customer_support",
        "priority": "high"
    }
})

# Nested metadata objects
peers = honcho.peers(filters={
    "metadata": {
        "profile": {
            "role": "admin",
            "department": "engineering"
        }
    }
})

(async () => {
    // Simple metadata equality
    const sessions = await honcho.sessions({
      filters: {
        metadata: {
          type: "customer_support",
          priority: "high"
        }
      }
    });

    // Nested metadata objects
    const peers = await honcho.peers({
      filters: {
        metadata: {
          profile: {
            role: "admin",
            department: "engineering"
          }
        }
      }
    });
})();

Advanced Metadata Queries

If you want to do advanced queries like these, make sure not to create metadata fields that use the same names as the included comparison operators! For example, if you have a metadata field called contains, it will conflict with the contains operator.

# Metadata with comparison operators
sessions = honcho.sessions(filters={
    "metadata": {
        "score": {"gte": 4.0, "lte": 5.0},
        "created_by": {"ne": "system"},
        "tags": {"contains": "important"}
    }
})

# Complex metadata conditions
messages = session.messages(filters={
    "AND": [
        {"metadata": {"sentiment": {"in": ["positive", "neutral"]}}},
        {"metadata": {"confidence": {"gt": 0.8}}},
        {"content": {"icontains": "thank"}}
    ]
})

(async () => {
    // Metadata with comparison operators
    const sessions = await honcho.sessions({
      filters: {
        metadata: {
          score: { gte: 4.0, lte: 5.0 },
          created_by: { ne: "system" },
          tags: { contains: "important" }
        }
      }
    });

    // Complex metadata conditions
    const messages = await session.messages({
      filters: {
        AND: [
          { metadata: { sentiment: { in: ["positive", "neutral"] } } },
          { metadata: { confidence: { gt: 0.8 } } },
          { content: { icontains: "thank" } }
        ]
      }
    });
})();

Wildcards

Use wildcards (*) to match any value for a field:

# Find all sessions with any peer_id (essentially all sessions)
sessions = honcho.sessions(filters={
    "peer_id": "*"
})

# Wildcard in lists - matches everything
messages = session.messages(filters={
    "peer_id": {"in": ["alice", "bob", "*"]}
})

# Metadata wildcards
sessions = honcho.sessions(filters={
    "metadata": {
        "type": "*",  # Any type
        "status": "active"  # But status must be active
    }
})

(async () => {
    // Find all sessions with any peer_id (essentially all sessions)
    const sessions = await honcho.sessions({
      filters: {
        peer_id: "*"
      }
    });

    // Wildcard in lists - matches everything
    const messages = await session.messages({
      filters: {
        peer_id: { in: ["alice", "bob", "*"] }
      }
    });

    // Metadata wildcards
    const filteredSessions = await honcho.sessions({
      filters: {
        metadata: {
          type: "*",  // Any type
          status: "active"  // But status must be active
        }
      }
    });
})();

Resource-Specific Examples

Filtering Workspaces

# Find workspaces by name pattern
workspaces = honcho.workspaces(filters={
    "name": {"contains": "prod"}
})

# Filter by metadata
workspaces = honcho.workspaces(filters={
    "metadata": {
        "environment": "production",
        "team": {"in": ["backend", "frontend", "devops"]}
    }
})

(async () => {
    // Find workspaces by name pattern
    const workspaces = await honcho.workspaces({
      filters: {
        name: { contains: "prod" }
      }
    });

    // Filter by metadata
    const workspaces = await honcho.workspaces({
      filters: {
        metadata: {
          environment: "production",
          team: { in: ["backend", "frontend", "devops"] }
        }
      }
    });
})();

Filtering Messages

# Find error messages from the last week
from datetime import datetime, timedelta

week_ago = (datetime.now() - timedelta(days=7)).isoformat()
messages = session.messages(filters={
    "AND": [
        {"content": {"icontains": "error"}},
        {"created_at": {"gte": week_ago}},
        {"metadata": {"level": {"in": ["error", "critical"]}}}
    ]
})

# Find messages in specific sessions with sentiment analysis
messages = session.messages(filters={
    "AND": [
        {"session_id": {"in": ["support-1", "support-2", "support-3"]}},
        {"metadata": {"sentiment": "negative"}},
        {"metadata": {"confidence": {"gte": 0.7}}}
    ]
})

(async () => {
    // Find error messages from the last week
    const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
    const messages = await session.messages({
      filters: {
        AND: [
          { content: { icontains: "error" } },
          { created_at: { gte: weekAgo } },
          { metadata: { level: { in: ["error", "critical"] } } }
        ]
      }
    });

    // Find messages in specific sessions with sentiment analysis
    const sentimentMessages = await session.messages({
      filters: {
        AND: [
          { session_id: { in: ["support-1", "support-2", "support-3"] } },
          { metadata: { sentiment: "negative" } },
          { metadata: { confidence: { gte: 0.7 } } }
        ]
      }
    });
})();

Filtering Conclusions

Conclusions are scoped to an observer/observed peer pair (accessed via peer.conclusions for self-conclusions or peer.conclusions_of(target) for conclusions about another peer). The observer and observed are filled in automatically by the scope, so the filters you pass add to them. The most useful conclusion-specific field is level, the reasoning level:

explicit — extracted directly from messages
deductive / inductive / contradiction — derived later during dreaming

A common request is to surface only the directly-stated facts and exclude anything inferred during dreaming — filter level to explicit:

# Only conclusions extracted directly from messages (exclude dream-derived)
explicit = peer.conclusions.list(filters={"level": "explicit"})

# Only dream-derived conclusions
derived = peer.conclusions.list(filters={"level": {"in": ["deductive", "inductive"]}})

# Same filtering on semantic search
results = peer.conclusions.query(
    "food preferences",
    filters={"level": "deductive"},
)

# Conclusions about another peer, explicit only
bob_explicit = peer.conclusions_of("bob").list(filters={"level": "explicit"})

(async () => {
    // Only conclusions extracted directly from messages (exclude dream-derived)
    const explicit = await peer.conclusions.list({ filters: { level: "explicit" } });

    // Only dream-derived conclusions
    const derived = await peer.conclusions.list({
      filters: { level: { in: ["deductive", "inductive"] } }
    });

    // Same filtering on semantic search (query, topK, distance, filters)
    const results = await peer.conclusions.query(
      "food preferences",
      10,
      undefined,
      { level: "deductive" }
    );

    // Conclusions about another peer, explicit only
    const bobExplicit = await peer.conclusionsOf("bob").list({
      filters: { level: "explicit" }
    });
})();

Error Handling

Handle filter errors gracefully:

from honcho.exceptions import FilterError

try:
    # Invalid filter - unsupported operator
    messages = session.messages(filters={
        "created_at": {"invalid_operator": "2024-01-01"}
    })
except FilterError as e:
    print(f"Filter error: {e}")
    # Handle the error appropriately

try:
    # Invalid column name
    sessions = honcho.sessions(filters={
        "nonexistent_field": "value"
    })
except FilterError as e:
    print(f"Invalid field: {e}")

(async () => {
    try {
      // Invalid filter - unsupported operator
      const messages = await session.messages({
        filters: {
          created_at: { invalid_operator: "2024-01-01" }
        }
      });
    } catch (error) {
      if (error.message.includes("filters")) {
        console.error(`Filter error: ${error.message}`);
        // Handle the error appropriately
      }
    }

    try {
      // Invalid column name
      const sessions = await honcho.sessions({
        filters: {
          nonexistent_field: "value"
        }
      });
    } catch (error) {
      console.error(`Invalid field: ${error.message}`);
    }
})();

Conclusion

Honcho’s filtering system provides powerful capabilities for querying your conversational data. By understanding how to:

Use simple equality filters and complex logical operators
Apply comparison operators for range and pattern matching
Filter metadata with nested conditions
Handle wildcards and dynamic filter construction
Follow best practices for performance and validation

You can build sophisticated applications that efficiently find and process exactly the conversations, messages, and insights you need from your Honcho data.

Introduction

Core Concepts

Features

Reference

Basic Filtering Concepts

Simple Filters

Logical Operators

AND Operator

OR Operator

NOT Operator

Combining Logical Operators

Comparison Operators

Numeric Comparisons

List Membership

Metadata Filtering

Basic Metadata Filtering

Advanced Metadata Queries

Wildcards

Resource-Specific Examples

Filtering Workspaces

Filtering Messages

Filtering Conclusions

Error Handling

Conclusion

​Basic Filtering Concepts

​Simple Filters

​Logical Operators

​AND Operator

​OR Operator

​NOT Operator

​Combining Logical Operators

​Comparison Operators

​Numeric Comparisons

​List Membership

​Metadata Filtering

​Basic Metadata Filtering

​Advanced Metadata Queries

​Wildcards

​Resource-Specific Examples

​Filtering Workspaces

​Filtering Messages

​Filtering Conclusions

​Error Handling

​Conclusion

Basic Filtering Concepts

Simple Filters

Logical Operators

AND Operator

OR Operator

NOT Operator

Combining Logical Operators

Comparison Operators

Numeric Comparisons

List Membership

Metadata Filtering

Basic Metadata Filtering

Advanced Metadata Queries

Wildcards

Resource-Specific Examples

Filtering Workspaces

Filtering Messages

Filtering Conclusions

Error Handling

Conclusion