Skip to content

cogchain Package

Shared contracts and interfaces for this Red-DiscordBot cog collection.

Why

Several cogs (e.g., langcore, mermaid, qdrant, spoilarr) currently reach into each other with getattr() calls. That works but throws away the benefits of defined interfaces, makes refactors risky, and hides missing features until runtime. We need a single place to publish Abstractions/Contracts/Interfaces that cogs can agree on without creating hard references between plugins.

What this package provides

  • Common interface definitions and data structures that cogs can import.
  • A neutral dependency target so cogs do not import each other directly.
  • A path toward cleaner type-checking and safer refactors across the cog set.

Project layout (keep it clean)

cogchain/
  README.md
  pyproject.toml
  cogchain/
    __init__.py
    interfaces/        # Abstractions / Interfaces / Protocols / ABCs
    models/            # Shared constants, types, and data models
    errors.py          # Exceptions / error contracts

The goal is to keep only interfaces, protocols, and shared models here—no implementation details. If a cog needs new cross-cog behavior, add or adjust the interface first, then implement it inside the individual cog.

How it is used

The shared interfaces let cogs talk to each other without direct imports. Langcore owns the runtime flow; provider and store cogs plug in by implementing the protocols defined here.

flowchart LR
    subgraph User Actions
        U[Discord User]
    end

    subgraph Langcore Cog
        LC[langcore commands.Cog]
        CM[ConversationManagerProtocol]
        HUB[ChainHubProtocol]
    end

    subgraph Providers
        OR[openrouter\nChainProvider]
        OL[ollama\nChainProvider]
    end

    subgraph Stores
        QD[qdrant\nChainStore]
    end

    U -->|messages| LC
    LC --> CM
    LC --> HUB
    LC -->|uses provider interface| OR
    LC -->|uses provider interface| OL
    LC -->|uses store interface| QD

Interfaces are also used by extension cogs to register tools and handlers without coupling.

Local development

Install in editable mode while building or consuming the interfaces locally:

pip install -e .

Update interfaces here first, then adjust consuming cogs to use the shared definitions instead of getattr() glue.

Publishing

The PyPI package will be published as cogchain once the interfaces stabilize. Until then, keep using the editable install for local dev and testing. When ready, bump the version, publish to PyPI, and update cogs to depend on the released package.