polyflux-core 0.0.1a0
Core protocols and interfaces for Polyflux - extensible client for any communication protocol
Requires Python: >=3.12
Keywords: core, interface, polyflux, protocol, typed

# Polyflux Core

Foundational Protocol interfaces for Polyflux client functionality using abstract, protocol-agnostic capabilities.

## Unified Client Protocol

**The `Client` Protocol** (`base.py`) is a comprehensive protocol that combines all umbrella protocols into a single
interface. It serves as:

1. A reference for the complete set of capabilities that a full-featured client implements
2. A type constraint for functions that require a maximally-capable client
3. A developmental guide for planning protocol support across client implementations

```python
from typing import Protocol, runtime_checkable
from polyflux.core import (
    BaseExchange,
    BaseConnection,
    BaseDiscovery,
    BaseState,
    BaseLifecycle,
    BaseConduit,
    BaseReliability,
    BaseConfiguration,
    BasePDUProcessor,
    BaseObservability,
)


@runtime_checkable
class Client(
    BaseExchange, BaseConnection, BaseDiscovery, BaseState, BaseLifecycle,
    BaseConduit, BaseReliability, BaseConfiguration, BasePDUProcessor,
    BaseObservability, Protocol
):
    """Comprehensive client protocol combining all capability domains."""
    ...
```

## Core Protocols

### Exchange (`exchange.py`)

**Umbrella Protocol**: `BaseExchange` - Enables bidirectional information transfer

- `SupportsSend`: Protocol for transmitting information
    - `send()`: Synchronous transmission operation
    - `asend()`: Asynchronous transmission operation

- `SupportsReceive`: Protocol for accepting information
    - `receive()`: Synchronous acceptance operation
    - `areceive()`: Asynchronous acceptance operation

- `SupportsExchange`: Protocol for atomic send-receive operations
    - `exchange()`: Synchronous transmit-then-accept cycle
    - `aexchange()`: Asynchronous transmit-then-accept cycle

### Connect (`connect.py`)

**Umbrella Protocol**: `BaseConnection` - Manages resource relationship lifecycles

- `SupportsConnect`: Protocol for establishing and managing resource relationships
    - `connect()` / `aconnect()`: Establish relationship with a resource
    - `disconnect()` / `adisconnect()`: Terminate relationship with a resource
    - `connected()` / `aconnected()`: Check relationship status

### Discovery (`discovery.py`)

**Umbrella Protocol**: `BaseDiscovery` - Enables dynamic resource exploration

- `SupportsServiceDiscovery`: For finding available functional resources
    - `discover_services()` / `adiscover_services()`: Locate available resources
    - `get_service_info()` / `aget_service_info()`: Get resource details

- `SupportsCapabilityDiscovery`: For identifying available abilities
    - `discover_capabilities()` / `adiscover_capabilities()`: Find supported abilities
    - `has_capability()` / `ahas_capability()`: Check if a specific ability is supported

- `SupportsSchemaDiscovery`: For identifying data structures
    - `discover_schemas()` / `adiscover_schemas()`: Find available structures
    - `get_schema()` / `aget_schema()`: Get definition for specific data structure

### State (`state.py`)

**Umbrella Protocol**: `BaseState` - Provides information persistence and portability

- `SupportsStatePersistence`: For maintaining information continuity across sessions
    - `save_state()` / `asave_state()`: Store operational state durably
    - `load_state()` / `aload_state()`: Retrieve previously stored information

- `SupportsStateTransfer`: For interchanging operational state between systems
    - `export_state()` / `aexport_state()`: Prepare operational state for transmission
    - `import_state()` / `aimport_state()`: Incorporate received operational state

### Lifecycle (`lifecycle.py`)

**Umbrella Protocol**: `BaseLifecycle` - Controls operational execution boundaries

- `SupportsContextManager`: Protocol for automatic resource acquisition and release
    - Standard resource management methods
    - Async resource management methods

- `SupportsTimeout`: For applying time constraints to operations
    - `with_timeout()`: Set default duration constraint
    - `timeout_after()`: Execute with specific duration constraint

- `SupportsCancel`: For terminating ongoing operations
    - `cancel()` / `acancel()`: Terminate an ongoing operation
    - `cancelled()` / `acancelled()`: Check operation termination status

### Conduit (`conduit.py`)

**Umbrella Protocol**: `BaseConduit` - Facilitates varied information flow patterns

- `SupportsStream`: Protocol for sequential data processing
    - `stream()`: Synchronous sequential processing
    - `astream()`: Asynchronous sequential processing

- `SupportsSubscribe`: Protocol for notification patterns
    - `subscribe()` / `asubscribe()`: Express interest in information categories
    - `unsubscribe()` / `aunsubscribe()`: Remove interest in information categories

- `SupportsPortal`: For two-way information exchange pathways
    - `open_portal()` / `aopen_portal()`: Establish bidirectional pathway
    - `close_portal()` / `aclose_portal()`: Close bidirectional pathway

### Reliability (`reliability.py`)

**Umbrella Protocol**: `BaseReliability` - Ensures operational robustness

- `SupportsErrorHandling`: For managing exceptional conditions
    - `on_error()`: Register specialized error processor
    - `handle_error()` / `ahandle_error()`: Process exceptional condition

- `SupportsRetry`: For operation reattempting strategies
    - `with_retry()`: Configure automatic reattempt behavior
    - `retry()` / `aretry()`: Explicitly reattempt an operation

- `SupportsCircuitBreaker`: For preventing cascading failures
    - `with_circuit_breaker()`: Configure automatic interruption behavior
    - `circuit_open()` / `acircuit_open()`: Check interruption status

- `SupportsCache`: For result reuse optimization
    - `with_cache()`: Configure result reuse strategy
    - `clear_cache()` / `aclear_cache()`: Invalidate stored results
    - `cached()` / `acached()`: Check if result is available for reuse

### Configurable (`configurable.py`)

**Umbrella Protocol**: `BaseConfiguration` - Enables dynamic parameter adjustment

- `SupportsAuthentication`: Protocol for identity verification
    - `authenticate()` / `aauthenticate()`: Verify component identity
    - `authenticated()` / `aauthenticated()`: Check identity verification status

- `SupportsConfiguration`: For operational parameter management
    - `configure()` / `aconfigure()`: Update operational parameters
    - `get_configuration()` / `aget_configuration()`: Retrieve current parameters

### Protocol Data Unit (`protocol_data_unit/`)

**Base Protocol Interfaces**: `Inbound` and `Outbound` - Defines fundamental PDU types

- `Inbound`: Protocol for incoming PDU types
    - `parse()`: Process and extract data from the raw PDU
    - `validate()`: Perform validation on the PDU
    - `get_metadata()`: Retrieve auxiliary information about the PDU

- `Outbound`: Protocol for outgoing PDU types
    - `serialize()`: Convert to raw transport format
    - `get_metadata()`: Retrieve auxiliary information about the PDU

**Umbrella Protocol**: `BasePDUProcessor` - Provides PDU transformation capabilities

- `SupportsMiddleware`: Protocol for processing chains
    - `add_middleware()` / `aadd_middleware()`: Add processor to chain
    - `remove_middleware()` / `aremove_middleware()`: Remove processor from chain

- `SupportsMetadata`: For auxiliary information management
    - `with_metadata()`: Add auxiliary information
    - `get_metadata()` / `aget_metadata()`: Retrieve auxiliary information

- `SupportsContentFormat`: For structure representation negotiation
    - `with_format()`: Set representation format
    - `get_supported_formats()` / `aget_supported_formats()`: List supported representations

- `SupportsTransformation`: For information structure conversion
    - `transform()` / `atransform()`: Convert information structure
    - `add_transformer()` / `aadd_transformer()`: Add conversion function

### Observability (`observability.py`)

**Umbrella Protocol**: `BaseObservability` - Enables system introspection

- `SupportsLogging`: For activity recording
    - `with_logger()`: Configure recording mechanism
    - `log()` / `alog()`: Record system activity

- `SupportsMetrics`: For quantitative measurement
    - `collect_metrics()` / `acollect_metrics()`: Gather quantitative measurements
    - `get_metrics()` / `aget_metrics()`: Retrieve accumulated measurements

- `SupportsTracing`: For execution flow tracking
    - `with_tracer()`: Configure flow tracking mechanism
    - `start_span()` / `astart_span()`: Begin tracking an execution segment
    - `end_span()` / `aend_span()`: Complete tracking an execution segment

## Design Principles

- Protocol-first development: Interfaces defined before implementations
- Abstract concept focus: All interfaces described in protocol-agnostic language
- Full typing with proper variance: Covariant and contravariant type parameters
- Async/sync API parity: All operations available in both modes
- Runtime protocol checking: Using `@runtime_checkable` for dynamic capability detection
- Structural typing: Capability detection through method signatures, not inheritance
- Compositional design: Umbrella protocols combine focused capability protocols

## Protocol Hierarchy

Polyflux core uses a tiered protocol hierarchy to enable flexible and modular implementations:

### 1. Capability Protocols

Individual Protocols that define specific focused capabilities (e.g., `SupportsSend`, `SupportsReceive`).

### 2. Umbrella Protocols

Each module provides an umbrella protocol that combines all the capability protocols in that module:

- **BaseExchange**: Complete bidirectional information transfer (SupportsSend + SupportsReceive + SupportsExchange)
- **BaseConnection**: Resource relationship management (SupportsConnect)
- **BaseDiscovery**: Complete resource and capability detection (SupportsServiceDiscovery +
  SupportsCapabilityDiscovery + SupportsSchemaDiscovery)
- **BaseState**: Information persistence and portability (SupportsStatePersistence + SupportsStateTransfer)
- **BaseLifecycle**: Full operational execution control (SupportsContextManager + SupportsTimeout + SupportsCancel)
- **BaseConduit**: Multi-pattern information flow (SupportsStream + SupportsSubscribe + SupportsPortal)
- **BaseReliability**: Comprehensive operational robustness (SupportsErrorHandling + SupportsRetry +
  SupportsCircuitBreaker + SupportsCache)
- **BaseConfiguration**: Dynamic parameter adjustment with security (SupportsAuthentication + SupportsConfiguration)
- **BasePDUProcessor**: Complete PDU transformation (SupportsMiddleware + SupportsMetadata + SupportsContentFormat +
  SupportsTransformation)
- **BaseObservability**: Full system introspection (SupportsLogging + SupportsMetrics + SupportsTracing)

### 3. Unified Client Protocol

The `Client` protocol combines all umbrella protocols into a single comprehensive interface that represents the complete
capability set.