Virginia Clemm Poe

A Python package for accessing Poe.com model data and pricing information.

Overview

Virginia Clemm Poe fetches and maintains Poe.com model data including pricing. It provides both a Python API for querying model data and a CLI for updating the dataset.

This link points to a static copy of the data file updated by the CLI tool. It does not reflect real-time changes from Poe's API.

Features

• Model Data Access: Query Poe.com models by ID, name, or other attributes
• Bot Information: Retrieve bot creator, description, and metadata
• Pricing Information: Scrape and sync pricing data for all models
• Pydantic Models: Typed data models for easy integration
• CLI Interface: Fire-based command line tool for data management
• Browser Automation: PlaywrightAuthor with Chrome for Testing
• Session Reuse: Reuse authenticated browser sessions across runs

Installation

pip install virginia-clemm-poe

Quick Start

Python API

from virginia_clemm_poe import api

# Search for models
models = api.search_bots("claude")
for model in models:
    print(f"{model.id}: {model.get_primary_cost()}")

# Get model by ID
model = api.get_bot_by_id("claude-3-opus")
if model and model.pricing:
    print(f"Cost: {model.get_primary_cost()}")
    print(f"Updated: {model.pricing.checked_at}")

# Get all models with pricing
priced_models = api.get_bots_with_pricing()
print(f"Found {len(priced_models)} models with pricing")

Programmatic Session Reuse

from virginia_clemm_poe.browser_pool import BrowserPool

# Use session reuse for authenticated scraping
async def scrape_with_session_reuse():
    pool = BrowserPool(reuse_sessions=True)
    await pool.start()
    
    # Get a page with existing authenticated session
    page = await pool.get_reusable_page()
    await page.goto("https://poe.com/some-protected-page")
    # Already logged in
    
    await pool.stop()

Command Line Interface

# Set up browser for web scraping
virginia-clemm-poe setup

# Update model data (bot info + pricing) - default behavior
export POE_API_KEY=your_api_key
virginia-clemm-poe update

# Update only bot info (creator, description)
virginia-clemm-poe update --info

# Update only pricing information
virginia-clemm-poe update --pricing

# Force update all data
virginia-clemm-poe update --force

# Search for models
virginia-clemm-poe search "gpt-4"

# Search with bot info displayed
virginia-clemm-poe search "claude" --show-bot-info

# List all models with summary
virginia-clemm-poe list

# List only models with pricing
virginia-clemm-poe list --with-pricing

NAME
    virginia-clemm-poe - Poe.com model data management CLI

SYNOPSIS
    virginia-clemm-poe COMMAND

DESCRIPTION
    Tool for accessing and maintaining Poe.com model information with pricing data.
    Use 'virginia-clemm-poe COMMAND --help' for detailed command info.

    Quick Start:
        1. virginia-clemm-poe setup     # Install browser
        2. virginia-clemm-poe update    # Fetch model data  
        3. virginia-clemm-poe search    # Query models

    Common Workflows:
        - Initial Setup: setup → update → search
        - Regular Use: search (data cached locally)
        - Maintenance: status → update (if needed)
        - Troubleshooting: doctor → follow recommendations

COMMANDS
    cache       Monitor cache performance
    clear_cache Clear cache and stored data
    doctor      Diagnose and fix issues
    list        List all available models
    search      Find models by name or ID
    setup       Install Chrome browser for scraping
    status      Check system health and data freshness
    update      Fetch latest model data from Poe

Session Reuse Workflow (Recommended)

Virginia Clemm Poe supports PlaywrightAuthor's session reuse feature, maintaining authenticated browser sessions across script runs.

# Step 1: Launch Chrome for Testing and log in manually
playwrightauthor browse

# Step 2: In the browser window, log into Poe.com
# The browser stays running after you close the terminal

# Step 3: Run virginia-clemm-poe commands
export POE_API_KEY=your_api_key
virginia-clemm-poe update --pricing

# The scraper reuses your logged-in session

Benefits:

• One-time authentication: Log in once, all scripts use that session
• Faster scraping: Skip login flows in automation
• More reliable: Avoid bot detection during login

API Reference

Core Functions

api.search_bots(query: str) -> List[PoeBot]

Search for models by ID or name (case-insensitive).

api.get_bot_by_id(model_id: str) -> Optional[PoeBot]

Get a specific model by its ID.

api.get_all_bots() -> List[PoeBot]

Get all available models.

api.get_bots_with_pricing() -> List[PoeBot]

Get all models that have pricing information.

api.get_bots_needing_update() -> List[PoeBot]

Get models that need pricing update.

api.reload_bots() -> BotCollection

Force reload models from disk.

Data Models

PoeBot

class PoeBot:
    id: str
    created: int
    owned_by: str
    root: str
    parent: Optional[str]
    architecture: Architecture
    pricing: Optional[Pricing]
    pricing_error: Optional[str]
    bot_info: Optional[BotInfo]

    def has_pricing() -> bool
    def needs_pricing_update() -> bool
    def get_primary_cost() -> Optional[str]

Architecture

class Architecture:
    input_modalities: List[str]
    output_modalities: List[str]
    modality: str

BotInfo

class BotInfo:
    creator: Optional[str]        # e.g., "@openai"
    description: Optional[str]    # Main bot description
    description_extra: Optional[str]  # Additional disclaimer text

Pricing

class Pricing:
    checked_at: datetime
    details: PricingDetails

PricingDetails

Flexible pricing details supporting various cost structures:

• Standard fields: input_text, input_image, bot_message, chat_history
• Alternative fields: total_cost, image_output, video_output, etc.
• Bot info field: initial_points_cost (e.g., "206+ points")

CLI Commands

setup

Set up browser for web scraping (handled automatically by PlaywrightAuthor).

virginia-clemm-poe setup

update

Update model data from Poe API and scrape additional information.

virginia-clemm-poe update [--info] [--pricing] [--all] [--force] [--verbose]

Options:

• --info: Update only bot info (creator, description)
• --pricing: Update only pricing information
• --all: Update both info and pricing (default)
• --api_key: Override POE_API_KEY environment variable
• --force: Force update even if data exists
• --debug_port: Chrome debug port (default: 9222)
• --verbose: Enable verbose logging

search

Search for models by ID or name.

virginia-clemm-poe search "claude" [--show-pricing] [--show-bot-info]

Options:

• --show-pricing: Show pricing information if available (default: True)
• --show-bot-info: Show bot info (creator, description) (default: False)

list

List all available models.

virginia-clemm-poe list [--with-pricing] [--limit 10]

Options:

• --with-pricing: Only show models with pricing information
• --limit: Limit number of results

Requirements

• Python 3.12+
• Chrome or Chromium browser (automatically managed by PlaywrightAuthor)
• Poe API key (set as POE_API_KEY environment variable)

Data Storage

Model data is stored in src/virginia_clemm_poe/data/poe_models.json within the package directory. The data includes:

• Basic model information (ID, name, capabilities)
• Detailed pricing structure
• Timestamps for data freshness

Development

Setting Up Development Environment

# Clone the repository
git clone https://github.com/twardoch/virginia-clemm-poe.git
cd virginia-clemm-poe

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv --python 3.12
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

# Set up browser for development
virginia-clemm-poe setup

Running Tests

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=virginia_clemm_poe

Dependencies

This package uses:

• uv for dependency management
• httpx for API requests
• playwrightauthor for browser automation
• pydantic for data models
• fire for CLI interface
• rich for terminal UI
• loguru for logging
• hatch-vcs for automatic versioning from git tags

API Examples

Get Model Information

from virginia_clemm_poe import api

# Get a specific model
model = api.get_bot_by_id("claude-3-opus")
if model:
    print(f"Model: {model.id}")
    print(f"Input modalities: {model.architecture.input_modalities}")
    if model.pricing:
        primary_cost = model.get_primary_cost()
        print(f"Cost: {primary_cost}")
        print(f"Last updated: {model.pricing.checked_at}")

# Search for models
gpt_models = api.search_bots("gpt")
for model in gpt_models:
    print(f"- {model.id}: {model.architecture.modality}")

Filter Models by Criteria

from virginia_clemm_poe import api

# Get all models with pricing
priced_models = api.get_bots_with_pricing()
print(f"Models with pricing: {len(priced_models)}")

# Get models needing pricing update
need_update = api.get_bots_needing_update()
print(f"Models needing update: {len(need_update)}")

# Get models with specific modality
all_models = api.get_all_bots()
text_to_image = [m for m in all_models if m.architecture.modality == "text->image"]
print(f"Text-to-image models: {len(text_to_image)}")

Working with Pricing Data

from virginia_clemm_poe import api

# Get pricing details for a model
model = api.get_bot_by_id("claude-3-haiku")
if model and model.pricing:
    details = model.pricing.details

    # Access standard pricing fields
    if details.input_text:
        print(f"Text input: {details.input_text}")
    if details.bot_message:
        print(f"Bot message: {details.bot_message}")

    # Alternative pricing formats
    if details.total_cost:
        print(f"Total cost: {details.total_cost}")

    # Get primary cost (auto-detected)
    print(f"Primary cost: {model.get_primary_cost()}")

Contributing

Contributions are welcome. Submit a Pull Request or open an issue for major changes.

Author

Adam Twardoch adam+github@twardoch.com

License

Licensed under the Apache License 2.0. See LICENSE file for details.

Acknowledgments

Named after Virginia Clemm Poe (1822–1847), wife of Edgar Allan Poe, reflecting the connection to Poe.com.

Disclaimer

This is an unofficial companion tool for Poe.com's API. It is not affiliated with or endorsed by Poe.com or Quora, Inc.