petrosa-contracts 0.1.0__tar.gz

petrosa_contracts-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: petrosa-contracts
+Version: 0.1.0
+Summary: Canonical shared pydantic contracts (Signal, TradingConfig) for the Petrosa trading path
+Author-email: Petrosa Team <dev@petrosa.com>
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# petrosa-contracts
+
+Canonical, shared `pydantic` contracts for the Petrosa trading path.
+
+This package resolves petrosa_k8s#1116: `contracts/signal.py` and
+`contracts/trading_config.py` were copy-pasted into `petrosa-cio/` and
+`petrosa-tradeengine/` and had diverged in both directions (CIO had
+`leverage`, tradeengine had `decision_id`; the `TradingConfigAudit.config_type`
+enum differed). One of those divergences (`leverage` reaching tradeengine)
+was the direct cause of `petrosa-tradeengine#599` — a P0 where every position
+traded at a hardcoded 10x leverage because the field was silently dropped by
+`extra="ignore"`.
+
+## What's here
+
+- `petrosa_contracts.signal.Signal` and its enums (`SignalType`,
+  `SignalStrength`, `TimeFrame`, `OrderType`, `TimeInForce`, `StrategyMode`) —
+  the reconciled superset of both repos' `Signal` models, with both
+  `leverage` and `decision_id`.
+- `petrosa_contracts.trading_config.TradingConfig`, `TradingConfigAudit`,
+  `LeverageStatus` — the reconciled superset, with `TradingConfigAudit`
+  supporting all four `config_type` values (`global`, `symbol`,
+  `symbol_side`, `strategy`).
+- Every model sets `model_config = ConfigDict(extra="forbid")`. A producer
+  field with no matching consumer attribute now raises `ValidationError` at
+  parse time instead of being silently discarded.
+
+## Installation
+
+Install the published package from PyPI:
+
+```bash
+pip install petrosa-contracts
+```
+
+For local development only, contributors with access to the private repository may
+install directly from the source tree:
+
+```bash
+pip install "petrosa-contracts @ git+https://github.com/PetroSa2/petrosa_k8s.git@main#subdirectory=petrosa-contracts"
+```
+
+This private-repository URL requires repository access and must not appear in a public
+consumer's `requirements.txt`. Tags named `petrosa-contracts-vX.Y.Z` trigger the
+publication workflow.
+
+## Usage
+
+```python
+from petrosa_contracts import Signal, TradingConfig
+
+signal = Signal(
+    strategy_id="orderbook_skew",
+    symbol="BTCUSDT",
+    action="buy",
+    confidence=0.82,
+    price=65000.0,
+    quantity=0.01,
+    current_price=65000.0,
+    source="petrosa-cio",
+    strategy="orderbook_skew",
+    leverage=5,
+    decision_id="a1b2c3d4e5f6",
+)
+
+# Any field neither producer nor consumer declared now raises immediately:
+Signal(**{**signal.model_dump(), "unexpected_field": 1})
+# -> pydantic.ValidationError: Extra inputs are not permitted
+```
+
+## Scope of petrosa_k8s#1116 covered by this package
+
+This PR creates the canonical package and its contract tests
+(petrosa_k8s#1116 AC: "exist in exactly one place", "superset reconciling
+both divergences", "`extra=forbid`", "contract test in CI"). It does
+**not** yet remove the vendored copies from `petrosa-cio/contracts/` and
+`petrosa-tradeengine/contracts/` or switch those services to import from
+this package — that requires coordinated, staged changes in each of those
+repos' own CI/deploy pipelines and is tracked as follow-up work:
+
+- `petrosa-cio`: migrate to `petrosa_contracts`, delete the vendored copy.
+- `petrosa-tradeengine`: migrate to `petrosa_contracts`, delete the vendored
+  copy.
+
+Both follow-ups should keep the same staged-rollout discipline the parent
+ticket calls for (log-then-enforce) for any field this package's
+`extra="forbid"` newly rejects that either service's real traffic still
+sends.
+
+## Development
+
+```bash
+cd petrosa-contracts
+pip install -e ".[dev]"
+pytest --cov=petrosa_contracts --cov-report=term-missing
+ruff check src/ tests/
+ruff format --check src/ tests/
+```

petrosa_contracts-0.1.0/README.md

@@ -0,0 +1,98 @@
+# petrosa-contracts
+
+Canonical, shared `pydantic` contracts for the Petrosa trading path.
+
+This package resolves petrosa_k8s#1116: `contracts/signal.py` and
+`contracts/trading_config.py` were copy-pasted into `petrosa-cio/` and
+`petrosa-tradeengine/` and had diverged in both directions (CIO had
+`leverage`, tradeengine had `decision_id`; the `TradingConfigAudit.config_type`
+enum differed). One of those divergences (`leverage` reaching tradeengine)
+was the direct cause of `petrosa-tradeengine#599` — a P0 where every position
+traded at a hardcoded 10x leverage because the field was silently dropped by
+`extra="ignore"`.
+
+## What's here
+
+- `petrosa_contracts.signal.Signal` and its enums (`SignalType`,
+  `SignalStrength`, `TimeFrame`, `OrderType`, `TimeInForce`, `StrategyMode`) —
+  the reconciled superset of both repos' `Signal` models, with both
+  `leverage` and `decision_id`.
+- `petrosa_contracts.trading_config.TradingConfig`, `TradingConfigAudit`,
+  `LeverageStatus` — the reconciled superset, with `TradingConfigAudit`
+  supporting all four `config_type` values (`global`, `symbol`,
+  `symbol_side`, `strategy`).
+- Every model sets `model_config = ConfigDict(extra="forbid")`. A producer
+  field with no matching consumer attribute now raises `ValidationError` at
+  parse time instead of being silently discarded.
+
+## Installation
+
+Install the published package from PyPI:
+
+```bash
+pip install petrosa-contracts
+```
+
+For local development only, contributors with access to the private repository may
+install directly from the source tree:
+
+```bash
+pip install "petrosa-contracts @ git+https://github.com/PetroSa2/petrosa_k8s.git@main#subdirectory=petrosa-contracts"
+```
+
+This private-repository URL requires repository access and must not appear in a public
+consumer's `requirements.txt`. Tags named `petrosa-contracts-vX.Y.Z` trigger the
+publication workflow.
+
+## Usage
+
+```python
+from petrosa_contracts import Signal, TradingConfig
+
+signal = Signal(
+    strategy_id="orderbook_skew",
+    symbol="BTCUSDT",
+    action="buy",
+    confidence=0.82,
+    price=65000.0,
+    quantity=0.01,
+    current_price=65000.0,
+    source="petrosa-cio",
+    strategy="orderbook_skew",
+    leverage=5,
+    decision_id="a1b2c3d4e5f6",
+)
+
+# Any field neither producer nor consumer declared now raises immediately:
+Signal(**{**signal.model_dump(), "unexpected_field": 1})
+# -> pydantic.ValidationError: Extra inputs are not permitted
+```
+
+## Scope of petrosa_k8s#1116 covered by this package
+
+This PR creates the canonical package and its contract tests
+(petrosa_k8s#1116 AC: "exist in exactly one place", "superset reconciling
+both divergences", "`extra=forbid`", "contract test in CI"). It does
+**not** yet remove the vendored copies from `petrosa-cio/contracts/` and
+`petrosa-tradeengine/contracts/` or switch those services to import from
+this package — that requires coordinated, staged changes in each of those
+repos' own CI/deploy pipelines and is tracked as follow-up work:
+
+- `petrosa-cio`: migrate to `petrosa_contracts`, delete the vendored copy.
+- `petrosa-tradeengine`: migrate to `petrosa_contracts`, delete the vendored
+  copy.
+
+Both follow-ups should keep the same staged-rollout discipline the parent
+ticket calls for (log-then-enforce) for any field this package's
+`extra="forbid"` newly rejects that either service's real traffic still
+sends.
+
+## Development
+
+```bash
+cd petrosa-contracts
+pip install -e ".[dev]"
+pytest --cov=petrosa_contracts --cov-report=term-missing
+ruff check src/ tests/
+ruff format --check src/ tests/
+```

petrosa_contracts-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "petrosa-contracts"
+version = "0.1.0"
+description = "Canonical shared pydantic contracts (Signal, TradingConfig) for the Petrosa trading path"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    { name = "Petrosa Team", email = "dev@petrosa.com" }
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "ruff>=0.1.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 88
+target-version = "0.1.0"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_classes = "Test*"
+python_functions = "test_*"
+addopts = "-v --cov=petrosa_contracts --cov-report=term-missing --cov-fail-under=40"
+
+[tool.coverage.run]
+source = ["petrosa_contracts"]
+omit = [
+    "*/tests/*",
+    "*/__pycache__/*",
+]
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+skip_covered = false

petrosa_contracts-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

petrosa_contracts-0.1.0/src/petrosa_contracts/__init__.py

@@ -0,0 +1,43 @@
+"""petrosa-contracts: canonical, shared pydantic contracts for the Petrosa trading path.
+
+This package is the single source of truth for the `Signal` and `TradingConfig`
+family of models previously copy-pasted into `petrosa-cio/contracts/` and
+`petrosa-tradeengine/contracts/` (petrosa_k8s#1116). All models here declare
+`model_config = ConfigDict(extra="forbid")`: because this package has no live
+consumers yet, there is no "silent divergence" blast radius to stage around —
+unlike flipping `extra="forbid"` on the two *existing* copies, which the
+originating ticket correctly identifies as unsafe to do blind against live
+traffic. Consuming services should construct these models directly from
+producer payloads so any unknown field raises at parse time instead of being
+silently dropped (the root cause of petrosa-tradeengine#599).
+"""
+
+from petrosa_contracts.signal import (
+    OrderType,
+    Signal,
+    SignalStrength,
+    SignalType,
+    StrategyMode,
+    TimeFrame,
+    TimeInForce,
+)
+from petrosa_contracts.trading_config import (
+    LeverageStatus,
+    TradingConfig,
+    TradingConfigAudit,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "OrderType",
+    "Signal",
+    "SignalStrength",
+    "SignalType",
+    "StrategyMode",
+    "TimeFrame",
+    "TimeInForce",
+    "LeverageStatus",
+    "TradingConfig",
+    "TradingConfigAudit",
+]

petrosa_contracts-0.1.0/src/petrosa_contracts/signal.py

@@ -0,0 +1,288 @@
+"""Canonical `Signal` contract shared by petrosa-cio and petrosa-tradeengine.
+
+Reconciles the two previously copy-pasted implementations
+(`petrosa-cio/contracts/signal.py`, `petrosa-tradeengine/contracts/signal.py`)
+into a single superset:
+
+- `leverage` (originally only on CIO's copy, ported to tradeengine's copy by
+  petrosa-tradeengine#599) is present here.
+- `decision_id` (originally only on tradeengine's copy) is present here.
+- `extra="forbid"` is set unconditionally. Unlike flipping this flag on an
+  *existing* copy with live producers/consumers already depending on
+  `extra="ignore"` (which the parent ticket, petrosa_k8s#1116, explicitly
+  warns must be staged behind a logging period — see the ticket's
+  "Sequencing" section), this package has no consumers yet, so there is
+  nothing depending on unknown fields being silently dropped. Forbidding
+  from day one is the safe default for a greenfield contract.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+logger = logging.getLogger(__name__)
+
+_MIN_UNIX_TS = 946684800  # 2000-01-01T00:00:00Z
+_MAX_UNIX_TS = 4102444800  # 2100-01-01T00:00:00Z
+
+
+class SignalType(StrEnum):
+    """Signal types for trading actions."""
+
+    BUY = "buy"
+    SELL = "sell"
+    HOLD = "hold"
+    CLOSE = "close"
+
+
+class SignalStrength(StrEnum):
+    """Signal strength levels."""
+
+    WEAK = "weak"
+    MEDIUM = "medium"
+    STRONG = "strong"
+    EXTREME = "extreme"
+
+
+class TimeFrame(StrEnum):
+    """Trading timeframes for signal analysis."""
+
+    TICK = "tick"
+    MINUTE_1 = "1m"
+    MINUTE_3 = "3m"
+    MINUTE_5 = "5m"
+    MINUTE_15 = "15m"
+    MINUTE_30 = "30m"
+    HOUR_1 = "1h"
+    HOUR_2 = "2h"
+    HOUR_4 = "4h"
+    HOUR_6 = "6h"
+    HOUR_8 = "8h"
+    HOUR_12 = "12h"
+    DAY_1 = "1d"
+    DAY_3 = "3d"
+    WEEK_1 = "1w"
+    MONTH_1 = "1M"
+
+
+class OrderType(StrEnum):
+    """Supported order types."""
+
+    MARKET = "market"
+    LIMIT = "limit"
+    STOP = "stop"
+    STOP_LIMIT = "stop_limit"
+    TAKE_PROFIT = "take_profit"
+    TAKE_PROFIT_LIMIT = "take_profit_limit"
+    CONDITIONAL_LIMIT = "conditional_limit"
+    CONDITIONAL_STOP = "conditional_stop"
+
+
+class TimeInForce(StrEnum):
+    """Order time in force options."""
+
+    GTC = "GTC"
+    IOC = "IOC"
+    FOK = "FOK"
+    GTX = "GTX"
+
+
+class StrategyMode(StrEnum):
+    """Strategy processing modes."""
+
+    DETERMINISTIC = "deterministic"
+    ML_LIGHT = "ml_light"
+    LLM_REASONING = "llm_reasoning"
+
+
+def _parse_datetime_aware(value: Any) -> datetime:
+    """Best-effort, timezone-aware datetime coercion.
+
+    Mirrors the two (near-identical) validators previously duplicated in
+    `petrosa-cio` and `petrosa-tradeengine`. Falls back to "now" on anything
+    unparseable rather than raising, matching prior behavior for both
+    consumers.
+    """
+    if isinstance(value, datetime):
+        return value if value.tzinfo is not None else value.replace(tzinfo=UTC)
+    if isinstance(value, int | float):
+        if _MIN_UNIX_TS <= value <= _MAX_UNIX_TS:
+            return datetime.fromtimestamp(value, UTC)
+        logger.warning(
+            "Unix timestamp %s out of valid range - using current time", value
+        )
+        return datetime.now(UTC)
+    if isinstance(value, str):
+        try:
+            return _parse_datetime_aware(datetime.fromisoformat(value))
+        except ValueError:
+            try:
+                return _parse_datetime_aware(float(value))
+            except (ValueError, TypeError):
+                logger.warning(
+                    "Invalid timestamp format '%s' - using current time", value
+                )
+                return datetime.now(UTC)
+    logger.warning("Invalid timestamp type %s - using current time", type(value))
+    return datetime.now(UTC)
+
+
+class Signal(BaseModel):
+    """Enhanced trading signal with advanced features (canonical, superset)."""
+
+    model_config = ConfigDict(
+        json_encoders={datetime: lambda v: v.isoformat()},
+        protected_namespaces=(),
+        extra="forbid",
+    )
+
+    # Core signal information
+    id: str | None = Field(None, description="Unique identifier for this signal")
+    strategy_id: str = Field(..., description="Unique identifier for the strategy")
+    signal_id: str | None = Field(None, description="Unique identifier for this signal")
+    decision_id: str | None = Field(
+        None,
+        description=(
+            "uuid4 hex string assigned by petrosa-cio for the decision that "
+            "produced this signal; None for strategy-direct signals"
+        ),
+    )
+    leverage: int | None = Field(
+        None,
+        ge=1,
+        description=(
+            "Admission-time leverage decided by CIO's leverage arbiter. "
+            "None for strategy-direct signals or legacy producers; the "
+            "consumer falls back to its configured default and should log "
+            "the fallback explicitly rather than silently applying a fixed "
+            "value (petrosa-tradeengine#599)."
+        ),
+    )
+    strategy_mode: StrategyMode = Field(
+        StrategyMode.DETERMINISTIC, description="Processing mode for this signal"
+    )
+
+    # Trading parameters
+    symbol: str = Field(..., description="Trading symbol (e.g., BTCUSDT)")
+    signal_type: SignalType | None = Field(
+        None, description="Signal type (buy/sell/hold/close) - deprecated, use action"
+    )
+    action: Literal["buy", "sell", "hold", "close"] = Field(
+        ..., description="Trading action"
+    )
+    confidence: float = Field(..., ge=0, le=1, description="Signal confidence (0-1)")
+    strength: SignalStrength = Field(
+        SignalStrength.MEDIUM, description="Signal strength level"
+    )
+
+    # Price and quantity information
+    price: float = Field(..., description="Signal price")
+    quantity: float = Field(..., description="Signal quantity")
+    current_price: float = Field(..., description="Current market price")
+    target_price: float | None = Field(None, description="Target execution price")
+
+    # Source and metadata
+    source: str = Field(..., description="Signal source")
+    strategy: str = Field(..., description="Strategy name")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Additional metadata"
+    )
+
+    # Timeframe information
+    timeframe: str = Field("1h", description="Timeframe used for signal analysis")
+
+    # Order configuration
+    order_type: OrderType = Field(OrderType.MARKET, description="Order type to execute")
+    time_in_force: TimeInForce = Field(
+        TimeInForce.GTC, description="Order time in force"
+    )
+    position_size_pct: float | None = Field(
+        None, ge=0, le=1, description="Position size as percentage of portfolio"
+    )
+    quote_quantity: float | None = Field(
+        None, description="Quote quantity for quote-based orders"
+    )
+
+    # Risk management
+    stop_loss: float | None = Field(None, description="Stop loss price")
+    stop_loss_pct: float | None = Field(
+        None, ge=0, le=1, description="Stop loss as percentage"
+    )
+    take_profit: float | None = Field(None, description="Take profit price")
+    take_profit_pct: float | None = Field(
+        None, ge=0, le=1, description="Take profit as percentage"
+    )
+
+    # Conditional orders
+    conditional_price: float | None = Field(
+        None, description="Price level for conditional execution"
+    )
+    conditional_direction: Literal["above", "below"] | None = Field(
+        None, description="Direction for conditional execution"
+    )
+    conditional_timeout: int | None = Field(
+        None, description="Timeout in seconds for conditional orders"
+    )
+
+    # Advanced order features
+    iceberg_quantity: float | None = Field(
+        None, description="Iceberg quantity for iceberg orders"
+    )
+    client_order_id: str | None = Field(None, description="Client-provided order ID")
+
+    # ML/LLM specific fields
+    model_confidence: float | None = Field(
+        None, ge=0, le=1, description="ML model confidence score"
+    )
+    model_features: dict[str, Any] | None = Field(
+        None, description="Features used by ML model"
+    )
+    llm_reasoning: str | None = Field(None, description="LLM reasoning for the signal")
+    llm_alternatives: list[dict[str, Any]] | None = Field(
+        None, description="Alternative actions considered by LLM"
+    )
+
+    # Market indicators
+    indicators: dict[str, Any] | None = Field(
+        None, description="Technical indicators and market data"
+    )
+
+    # Metadata
+    rationale: str | None = Field(
+        None, description="Human-readable rationale for the signal"
+    )
+    meta: dict[str, Any] = Field(
+        default_factory=dict, description="Additional metadata"
+    )
+
+    # Timestamp
+    timestamp: datetime = Field(
+        default_factory=lambda: datetime.now(UTC), description="Signal timestamp"
+    )
+
+    @field_validator("timestamp", mode="before")
+    @classmethod
+    def validate_timestamp(cls, v: Any) -> datetime:
+        """Ensure timestamp is timezone-aware."""
+        return _parse_datetime_aware(v)
+
+    @field_validator("confidence", "model_confidence")
+    @classmethod
+    def validate_confidence(cls, v: Any) -> float | None:
+        """Validate confidence values."""
+        if v is not None and (v < 0 or v > 1):
+            raise ValueError("Confidence must be between 0 and 1")
+        return float(v) if v is not None else None
+
+    @field_validator("position_size_pct", "stop_loss_pct", "take_profit_pct")
+    @classmethod
+    def validate_percentages(cls, v: Any) -> float | None:
+        """Validate percentage values."""
+        if v is not None and (v < 0 or v > 1):
+            raise ValueError("Percentage must be between 0 and 1")
+        return float(v) if v is not None else None

petrosa_contracts-0.1.0/src/petrosa_contracts/trading_config.py

@@ -0,0 +1,270 @@
+"""Canonical `TradingConfig` family shared by petrosa-cio and petrosa-tradeengine.
+
+Reconciles the two previously copy-pasted implementations
+(`petrosa-cio/contracts/trading_config.py`,
+`petrosa-tradeengine/contracts/trading_config.py`) into a single superset:
+
+- `TradingConfigAudit.config_type` includes tradeengine's fourth value,
+  `"strategy"`, in addition to CIO's three (`global`, `symbol`, `symbol_side`).
+- `TradingConfigAudit.strategy_id` (tradeengine-only) is present here.
+- `TradingConfig.strategy_id` docstring uses tradeengine's broader wording
+  (both repos' fields were functionally identical; only the description
+  text differed).
+- `extra="forbid"` is set on every model here (see `signal.py` module
+  docstring for the rationale — this package is greenfield, so there is no
+  existing traffic to break by forbidding unknown fields immediately).
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class TradingConfig(BaseModel):
+    """
+    Trading configuration model.
+
+    Represents a complete configuration for trading execution,
+    either global (applied to all symbols) or symbol/side-specific.
+
+    Configuration Hierarchy:
+    - Global: Applies to all symbols and all sides
+    - Symbol: Applies to specific symbol, both LONG and SHORT
+    - Strategy: Applies to a specific strategy ID (e.g., 'orderbook_skew')
+    - Symbol-Side: Applies to specific symbol and specific side only
+    """
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "id": "507f1f77bcf86cd799439011",  # pragma: allowlist secret
+                "symbol": "BTCUSDT",
+                "side": "LONG",
+                "parameters": {
+                    "leverage": 10,
+                    "position_size_pct": 0.1,
+                    "stop_loss_pct": 2.0,
+                    "take_profit_pct": 5.0,
+                },
+                "version": 3,
+                "created_at": "2025-10-20T10:30:00Z",
+                "updated_at": "2025-10-20T14:45:00Z",
+                "created_by": "llm_agent_v1",
+                "metadata": {
+                    "notes": "Optimized for BTC long positions",
+                    "performance": "+15% win rate",
+                },
+            }
+        },
+        extra="forbid",
+    )
+
+    id: str | None = Field(None, description="Configuration ID")
+
+    # Scope identifiers
+    strategy_id: str | None = Field(
+        None, description="Strategy identifier (None for global/symbol configs)"
+    )
+    symbol: str | None = Field(
+        None, description="Trading symbol (None for global configs, e.g., 'BTCUSDT')"
+    )
+    side: Literal["LONG", "SHORT"] | None = Field(
+        None, description="Position side (None for global/symbol configs)"
+    )
+
+    # Configuration data
+    parameters: dict[str, Any] = Field(
+        ..., description="Trading parameters as key-value pairs"
+    )
+
+    # Versioning
+    version: int = Field(
+        1, description="Configuration version number (incremented on updates)"
+    )
+
+    # Timestamps
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        description="When configuration was created",
+    )
+    updated_at: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        description="When configuration was last updated",
+    )
+
+    # Audit
+    created_by: str = Field(
+        ..., description="Who/what created this config (e.g., 'llm_agent_v1', 'admin')"
+    )
+
+    # Additional metadata
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional metadata (notes, performance metrics, etc.)",
+    )
+
+    @field_validator("side")
+    @classmethod
+    def validate_side(cls, v: str | None) -> str | None:
+        """Validate position side."""
+        if v is not None and v not in ["LONG", "SHORT"]:
+            raise ValueError("Side must be 'LONG' or 'SHORT'")
+        return v
+
+    def get_scope_key(self) -> str:
+        """Get unique scope key for this config."""
+        if self.side:
+            return f"{self.symbol}:{self.side}"
+        elif self.symbol:
+            return self.symbol
+        return "global"
+
+
+class TradingConfigAudit(BaseModel):
+    """
+    Audit trail record for trading configuration changes.
+
+    Tracks all modifications to trading configurations for compliance,
+    debugging, and performance analysis.
+    """
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "id": "audit-123",
+                "config_type": "symbol_side",
+                "symbol": "BTCUSDT",
+                "side": "LONG",
+                "action": "update",
+                "parameters_before": {"leverage": 10},
+                "parameters_after": {"leverage": 15},
+                "version_before": 2,
+                "version_after": 3,
+                "changed_by": "llm_agent_v1",
+                "reason": "Increasing leverage for bullish market conditions",
+                "timestamp": "2025-10-20T15:00:00Z",
+                "metadata": {"ip_address": "192.168.1.1"},
+            }
+        },
+        extra="forbid",
+    )
+
+    id: str | None = Field(None, description="Audit record ID")
+
+    # Scope of change
+    config_type: Literal["global", "symbol", "symbol_side", "strategy"] = Field(
+        ..., description="Type of configuration that was changed"
+    )
+    symbol: str | None = Field(None, description="Symbol if applicable")
+    side: Literal["LONG", "SHORT"] | None = Field(
+        None, description="Side if applicable"
+    )
+    strategy_id: str | None = Field(None, description="Strategy if applicable")
+
+    # Change details
+    action: Literal["create", "update", "delete"] = Field(
+        ..., description="Action performed"
+    )
+
+    # Before/after state
+    parameters_before: dict[str, Any] | None = Field(
+        None, description="Parameters before the change"
+    )
+    parameters_after: dict[str, Any] | None = Field(
+        None, description="Parameters after the change"
+    )
+    version_before: int | None = Field(
+        None, description="Version number before the change"
+    )
+    version_after: int | None = Field(
+        None, description="Version number after the change"
+    )
+
+    # Audit metadata
+    changed_by: str = Field(..., description="Who/what made the change")
+    reason: str | None = Field(None, description="Reason for the change")
+    timestamp: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        description="When the change occurred",
+    )
+
+    # Additional context
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Additional audit metadata"
+    )
+
+    def get_change_summary(self) -> str:
+        """Get human-readable summary of the change."""
+        if self.strategy_id:
+            return f"{self.action.upper()} strategy {self.strategy_id} by {self.changed_by}"
+        scope = f"{self.symbol or 'global'}"
+        if self.side:
+            scope += f"-{self.side}"
+        return f"{self.action.upper()} {scope} by {self.changed_by}"
+
+
+class LeverageStatus(BaseModel):
+    """
+    Leverage status tracking model.
+
+    Tracks the difference between configured leverage (in our system)
+    and actual leverage (on Binance exchange) for each symbol.
+    """
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "id": "lev-status-btc",
+                "symbol": "BTCUSDT",
+                "configured_leverage": 10,
+                "actual_leverage": 10,
+                "last_sync_at": "2025-10-20T15:00:00Z",
+                "last_sync_success": True,
+                "last_sync_error": None,
+                "updated_at": "2025-10-20T15:00:00Z",
+            }
+        },
+        extra="forbid",
+    )
+
+    id: str | None = Field(None, description="Status record ID")
+
+    symbol: str = Field(..., description="Trading symbol")
+
+    # Leverage values
+    configured_leverage: int = Field(
+        ..., description="Leverage configured in our system", ge=1, le=125
+    )
+    actual_leverage: int | None = Field(
+        None, description="Actual leverage on Binance (None if unknown)", ge=1, le=125
+    )
+
+    # Sync status
+    last_sync_at: datetime | None = Field(
+        None, description="When leverage was last synced with Binance"
+    )
+    last_sync_success: bool = Field(
+        False, description="Whether last sync attempt was successful"
+    )
+    last_sync_error: str | None = Field(
+        None, description="Error message if sync failed"
+    )
+
+    # Metadata
+    updated_at: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        description="When this record was last updated",
+    )
+
+    def is_synced(self) -> bool:
+        """Check if configured and actual leverage match."""
+        if self.actual_leverage is None:
+            return False
+        return self.configured_leverage == self.actual_leverage
+
+    def needs_sync(self) -> bool:
+        """Check if leverage needs to be synced."""
+        return not self.is_synced()

petrosa_contracts-0.1.0/src/petrosa_contracts.egg-info/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: petrosa-contracts
+Version: 0.1.0
+Summary: Canonical shared pydantic contracts (Signal, TradingConfig) for the Petrosa trading path
+Author-email: Petrosa Team <dev@petrosa.com>
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# petrosa-contracts
+
+Canonical, shared `pydantic` contracts for the Petrosa trading path.
+
+This package resolves petrosa_k8s#1116: `contracts/signal.py` and
+`contracts/trading_config.py` were copy-pasted into `petrosa-cio/` and
+`petrosa-tradeengine/` and had diverged in both directions (CIO had
+`leverage`, tradeengine had `decision_id`; the `TradingConfigAudit.config_type`
+enum differed). One of those divergences (`leverage` reaching tradeengine)
+was the direct cause of `petrosa-tradeengine#599` — a P0 where every position
+traded at a hardcoded 10x leverage because the field was silently dropped by
+`extra="ignore"`.
+
+## What's here
+
+- `petrosa_contracts.signal.Signal` and its enums (`SignalType`,
+  `SignalStrength`, `TimeFrame`, `OrderType`, `TimeInForce`, `StrategyMode`) —
+  the reconciled superset of both repos' `Signal` models, with both
+  `leverage` and `decision_id`.
+- `petrosa_contracts.trading_config.TradingConfig`, `TradingConfigAudit`,
+  `LeverageStatus` — the reconciled superset, with `TradingConfigAudit`
+  supporting all four `config_type` values (`global`, `symbol`,
+  `symbol_side`, `strategy`).
+- Every model sets `model_config = ConfigDict(extra="forbid")`. A producer
+  field with no matching consumer attribute now raises `ValidationError` at
+  parse time instead of being silently discarded.
+
+## Installation
+
+Install the published package from PyPI:
+
+```bash
+pip install petrosa-contracts
+```
+
+For local development only, contributors with access to the private repository may
+install directly from the source tree:
+
+```bash
+pip install "petrosa-contracts @ git+https://github.com/PetroSa2/petrosa_k8s.git@main#subdirectory=petrosa-contracts"
+```
+
+This private-repository URL requires repository access and must not appear in a public
+consumer's `requirements.txt`. Tags named `petrosa-contracts-vX.Y.Z` trigger the
+publication workflow.
+
+## Usage
+
+```python
+from petrosa_contracts import Signal, TradingConfig
+
+signal = Signal(
+    strategy_id="orderbook_skew",
+    symbol="BTCUSDT",
+    action="buy",
+    confidence=0.82,
+    price=65000.0,
+    quantity=0.01,
+    current_price=65000.0,
+    source="petrosa-cio",
+    strategy="orderbook_skew",
+    leverage=5,
+    decision_id="a1b2c3d4e5f6",
+)
+
+# Any field neither producer nor consumer declared now raises immediately:
+Signal(**{**signal.model_dump(), "unexpected_field": 1})
+# -> pydantic.ValidationError: Extra inputs are not permitted
+```
+
+## Scope of petrosa_k8s#1116 covered by this package
+
+This PR creates the canonical package and its contract tests
+(petrosa_k8s#1116 AC: "exist in exactly one place", "superset reconciling
+both divergences", "`extra=forbid`", "contract test in CI"). It does
+**not** yet remove the vendored copies from `petrosa-cio/contracts/` and
+`petrosa-tradeengine/contracts/` or switch those services to import from
+this package — that requires coordinated, staged changes in each of those
+repos' own CI/deploy pipelines and is tracked as follow-up work:
+
+- `petrosa-cio`: migrate to `petrosa_contracts`, delete the vendored copy.
+- `petrosa-tradeengine`: migrate to `petrosa_contracts`, delete the vendored
+  copy.
+
+Both follow-ups should keep the same staged-rollout discipline the parent
+ticket calls for (log-then-enforce) for any field this package's
+`extra="forbid"` newly rejects that either service's real traffic still
+sends.
+
+## Development
+
+```bash
+cd petrosa-contracts
+pip install -e ".[dev]"
+pytest --cov=petrosa_contracts --cov-report=term-missing
+ruff check src/ tests/
+ruff format --check src/ tests/
+```

petrosa_contracts-0.1.0/src/petrosa_contracts.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/petrosa_contracts/__init__.py
+src/petrosa_contracts/signal.py
+src/petrosa_contracts/trading_config.py
+src/petrosa_contracts.egg-info/PKG-INFO
+src/petrosa_contracts.egg-info/SOURCES.txt
+src/petrosa_contracts.egg-info/dependency_links.txt
+src/petrosa_contracts.egg-info/requires.txt
+src/petrosa_contracts.egg-info/top_level.txt
+tests/test_signal.py
+tests/test_trading_config.py

petrosa_contracts-0.1.0/src/petrosa_contracts.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

petrosa_contracts-0.1.0/src/petrosa_contracts.egg-info/requires.txt

@@ -0,0 +1,6 @@
+pydantic>=2.0.0
+
+[dev]
+pytest>=7.0.0
+pytest-cov>=4.0.0
+ruff>=0.1.0

petrosa_contracts-0.1.0/src/petrosa_contracts.egg-info/top_level.txt

@@ -0,0 +1 @@
+petrosa_contracts

petrosa_contracts-0.1.0/tests/test_signal.py

@@ -0,0 +1,120 @@
+"""Contract tests for `petrosa_contracts.signal.Signal`.
+
+These tests are the petrosa_k8s#1116 AC4 deliverable: "A contract test runs
+in CI that fails when a producer emits a field no consumer declares." They
+encode the exact payload shapes petrosa-cio and petrosa-tradeengine
+currently produce/consume so any future drift between a producer and this
+canonical contract fails CI immediately.
+"""
+
+from datetime import UTC, datetime
+
+import pytest
+from pydantic import ValidationError
+
+from petrosa_contracts.signal import (
+    OrderType,
+    Signal,
+    SignalStrength,
+    StrategyMode,
+    TimeInForce,
+)
+
+BASE_REQUIRED_FIELDS = {
+    "strategy_id": "orderbook_skew",
+    "symbol": "BTCUSDT",
+    "action": "buy",
+    "confidence": 0.75,
+    "price": 65000.0,
+    "quantity": 0.01,
+    "current_price": 65000.5,
+    "source": "petrosa-cio",
+    "strategy": "orderbook_skew",
+}
+
+
+def test_minimal_signal_constructs_with_only_required_fields():
+    signal = Signal(**BASE_REQUIRED_FIELDS)
+    assert signal.symbol == "BTCUSDT"
+    assert signal.action == "buy"
+    assert signal.leverage is None
+    assert signal.decision_id is None
+    assert signal.strength == SignalStrength.MEDIUM
+    assert signal.order_type == OrderType.MARKET
+    assert signal.time_in_force == TimeInForce.GTC
+    assert signal.strategy_mode == StrategyMode.DETERMINISTIC
+
+
+def test_signal_accepts_cio_leverage_field():
+    """petrosa-cio/cio/output/translator.py:90 emits `leverage` on every payload."""
+    signal = Signal(**BASE_REQUIRED_FIELDS, leverage=5)
+    assert signal.leverage == 5
+
+
+def test_signal_accepts_tradeengine_decision_id_field():
+    """petrosa-tradeengine attaches `decision_id` to CIO-originated signals."""
+    signal = Signal(**BASE_REQUIRED_FIELDS, decision_id="a1b2c3d4e5f6")
+    assert signal.decision_id == "a1b2c3d4e5f6"
+
+
+def test_signal_accepts_both_leverage_and_decision_id_simultaneously():
+    """The reconciled superset: both previously-copy-pasted-only fields at once."""
+    signal = Signal(**BASE_REQUIRED_FIELDS, leverage=10, decision_id="deadbeef")
+    assert signal.leverage == 10
+    assert signal.decision_id == "deadbeef"
+
+
+def test_signal_rejects_unknown_field():
+    """The core petrosa_k8s#1116 fix: `extra='forbid'` instead of silent drop.
+
+    This is the exact failure mode that hid petrosa-tradeengine#599: a
+    producer field with no matching consumer attribute must raise, not
+    vanish.
+    """
+    with pytest.raises(ValidationError):
+        Signal(**BASE_REQUIRED_FIELDS, made_up_field_no_consumer_declares="x")
+
+
+def test_signal_leverage_must_be_positive():
+    with pytest.raises(ValidationError):
+        Signal(**BASE_REQUIRED_FIELDS, leverage=0)
+
+
+@pytest.mark.parametrize(
+    "confidence",
+    [-0.01, 1.01],
+)
+def test_signal_confidence_out_of_range_rejected(confidence):
+    with pytest.raises(ValidationError):
+        Signal(**{**BASE_REQUIRED_FIELDS, "confidence": confidence})
+
+
+def test_signal_timestamp_defaults_to_timezone_aware_now():
+    signal = Signal(**BASE_REQUIRED_FIELDS)
+    assert signal.timestamp.tzinfo is not None
+
+
+def test_signal_timestamp_accepts_iso_string():
+    signal = Signal(**BASE_REQUIRED_FIELDS, timestamp="2026-01-01T00:00:00+00:00")
+    assert signal.timestamp == datetime(2026, 1, 1, tzinfo=UTC)
+
+
+def test_signal_timestamp_accepts_naive_datetime_and_localizes_utc():
+    naive = datetime(2026, 1, 1, 12, 0, 0)
+    signal = Signal(**BASE_REQUIRED_FIELDS, timestamp=naive)
+    assert signal.timestamp.tzinfo is not None
+
+
+def test_signal_timestamp_falls_back_to_now_on_garbage_input():
+    signal = Signal(**BASE_REQUIRED_FIELDS, timestamp="not-a-timestamp")
+    assert signal.timestamp.tzinfo is not None
+
+
+def test_signal_roundtrips_through_model_dump():
+    """Producer -> dict -> wire -> consumer round trip must be lossless."""
+    original = Signal(**BASE_REQUIRED_FIELDS, leverage=3, decision_id="abc123")
+    dumped = original.model_dump(mode="json")
+    reconstructed = Signal(**dumped)
+    assert reconstructed.leverage == original.leverage
+    assert reconstructed.decision_id == original.decision_id
+    assert reconstructed.symbol == original.symbol

petrosa_contracts-0.1.0/tests/test_trading_config.py

@@ -0,0 +1,113 @@
+"""Contract tests for `petrosa_contracts.trading_config`.
+
+Encodes the reconciled `TradingConfigAudit.config_type` enum (petrosa-cio's
+three values plus tradeengine's `"strategy"` addition) and the shared
+`extra="forbid"` behavior.
+"""
+
+import pytest
+from pydantic import ValidationError
+
+from petrosa_contracts.trading_config import (
+    LeverageStatus,
+    TradingConfig,
+    TradingConfigAudit,
+)
+
+
+def test_trading_config_minimal():
+    cfg = TradingConfig(parameters={"leverage": 10}, created_by="llm_agent_v1")
+    assert cfg.version == 1
+    assert cfg.get_scope_key() == "global"
+
+
+def test_trading_config_symbol_side_scope_key():
+    cfg = TradingConfig(
+        symbol="BTCUSDT",
+        side="LONG",
+        parameters={"leverage": 10},
+        created_by="admin",
+    )
+    assert cfg.get_scope_key() == "BTCUSDT:LONG"
+
+
+def test_trading_config_rejects_invalid_side():
+    with pytest.raises(ValidationError):
+        TradingConfig(symbol="BTCUSDT", side="UP", parameters={}, created_by="admin")
+
+
+def test_trading_config_rejects_unknown_field():
+    with pytest.raises(ValidationError):
+        TradingConfig(
+            parameters={},
+            created_by="admin",
+            unknown_field_no_consumer_declares=True,
+        )
+
+
+@pytest.mark.parametrize("config_type", ["global", "symbol", "symbol_side", "strategy"])
+def test_trading_config_audit_accepts_all_reconciled_config_types(config_type):
+    """`"strategy"` was tradeengine-only; the other three were shared.
+
+    This is the reconciled superset from petrosa_k8s#1116.
+    """
+    audit = TradingConfigAudit(
+        config_type=config_type,
+        action="update",
+        changed_by="llm_agent_v1",
+    )
+    assert audit.config_type == config_type
+
+
+def test_trading_config_audit_strategy_scoped_summary():
+    audit = TradingConfigAudit(
+        config_type="strategy",
+        strategy_id="orderbook_skew",
+        action="update",
+        changed_by="llm_agent_v1",
+    )
+    assert "strategy orderbook_skew" in audit.get_change_summary()
+
+
+def test_trading_config_audit_symbol_side_summary():
+    audit = TradingConfigAudit(
+        config_type="symbol_side",
+        symbol="BTCUSDT",
+        side="LONG",
+        action="update",
+        changed_by="llm_agent_v1",
+    )
+    assert audit.get_change_summary() == "UPDATE BTCUSDT-LONG by llm_agent_v1"
+
+
+def test_trading_config_audit_rejects_unknown_field():
+    with pytest.raises(ValidationError):
+        TradingConfigAudit(
+            config_type="global",
+            action="update",
+            changed_by="llm_agent_v1",
+            made_up_field=1,
+        )
+
+
+def test_leverage_status_sync_check():
+    status = LeverageStatus(
+        symbol="BTCUSDT", configured_leverage=10, actual_leverage=10
+    )
+    assert status.is_synced()
+    assert not status.needs_sync()
+
+
+def test_leverage_status_out_of_sync():
+    status = LeverageStatus(symbol="BTCUSDT", configured_leverage=10, actual_leverage=5)
+    assert not status.is_synced()
+    assert status.needs_sync()
+
+
+def test_leverage_status_rejects_unknown_field():
+    with pytest.raises(ValidationError):
+        LeverageStatus(
+            symbol="BTCUSDT",
+            configured_leverage=10,
+            made_up_field=1,
+        )