fba-bench-core 1.0.0__tar.gz

fba_bench_core-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 FBA-Bench Core Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fba_bench_core-1.0.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: fba-bench-core
+Version: 1.0.0
+Summary: Core interfaces, data models, and events for the FBA-Bench simulation platform.
+License: Apache-2.0
+License-File: LICENSE
+Keywords: benchmarking,simulation,fba,pydantic,typing
+Author: FBA Team
+Author-email: devnull@example.com
+Requires-Python: >=3.11,<4.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Dist: pydantic (>=2.0,<3.0)
+Project-URL: Documentation, https://your-org.github.io/fba-bench-core
+Project-URL: Homepage, https://github.com/your-org/fba-bench-core
+Project-URL: Issues, https://github.com/your-org/fba-bench-core/issues
+Project-URL: Repository, https://github.com/your-org/fba-bench-core
+Description-Content-Type: text/markdown
+
+# FBA-Bench Core — Contract-first Core Library
+
+Overview
+
+FBA-Bench Core is a compact, contract-first library for building and
+simulating Fulfillment-By-Amazon-style (FBA) business automation scenarios.
+The rebuilt core emphasizes explicit, versioned contracts (Pydantic v2 models)
+for domain models, events, commands, and typed configuration objects so
+downstream projects can reliably validate and integrate simulation logic.
+
+Key principles
+
+- Contract-first: canonical Pydantic v2 models are the single source of truth.
+- Typed, immutable configs: configuration objects are frozen models; use
+  model_copy(update={...}) to derive modified instances.
+- Explicit events/commands: typed discriminated unions with strict validation
+  (extra="forbid") to make integration predictable.
+
+Core modules
+
+- Domain models: [`src/fba_bench_core/domain/models.py`](src/fba_bench_core/domain/models.py:1)
+  - Product, InventorySnapshot, CompetitorListing, Competitor, DemandProfile
+- Events & Commands: [`src/fba_bench_core/domain/events.py`](src/fba_bench_core/domain/events.py:1)
+  - Typed BaseEvent/BaseCommand hierarchy and concrete events like SaleOccurred,
+    StockReplenished, PromotionLaunched; commands like AdjustPriceCommand,
+    PlaceReplenishmentOrderCommand.
+- Agent/service base classes: [`src/fba_bench_core/agents/base.py`](src/fba_bench_core/agents/base.py:1)
+  and [`src/fba_bench_core/services/base.py`](src/fba_bench_core/services/base.py:1)
+- Typed configs: [`src/fba_bench_core/config.py`](src/fba_bench_core/config.py:1)
+  - BaseAgentConfig, BaseServiceConfig (immutable, extra="forbid")
+
+Quick start (Poetry)
+
+Clone and install with Poetry:
+
+```bash
+git clone <repo-url>
+cd FBA-Bench-core
+poetry install
+```
+
+Run the test suite:
+
+```bash
+poetry run pytest -q
+```
+
+Using Core from another project
+
+1. Add FBA-Bench Core as a dependency (editable/local for development):
+
+```bash
+pip install -e /path/to/FBA-Bench-core
+```
+
+2. Import domain models and instantiate typed configs:
+
+```python
+from fba_bench_core.domain.models import Product
+from fba_bench_core.config import BaseAgentConfig
+
+p = Product(product_id="sku-1", cost="1.00", price="2.00", stock=10)
+cfg = BaseAgentConfig(agent_id="pricing-agent", poll_interval_seconds=30)
+```
+
+Migration guidance
+
+If you are upgrading from a legacy core:
+- See the migration guide: [`docs/migration-guide.md`](docs/migration-guide.md:1)
+- Key actions: import canonical models, convert numeric values to Decimal,
+  and replace mutable dict-based configs with typed Base*Config models.
+
+Tests, linting and quality commands
+
+The CI pipeline runs formatting, linting, type-checking and tests. Locally you
+can run the same commands via Poetry:
+
+```bash
+poetry run black src tests
+poetry run isort src tests
+poetry run flake8 src tests
+poetry run mypy
+poetry run pytest
+```
+
+Packaging & versioning workflow
+
+- CHANGELOG.md is generated from small towncrier fragments placed under
+  [`newsfragments/`](newsfragments/:1) and built with `towncrier`.
+- To add a changelog fragment: create a brief file `newsfragments/NN.description`
+  then run `poetry run towncrier build --yes`.
+- Version tooling: this repository includes [.bumpver.toml](.bumpver.toml:1)
+  and uses dynamic versioning in the packaging pipeline. Follow project policy
+  for release tagging and bumping; maintainers should prefer automated tools
+  (bumpver) that integrate with CI.
+
+Architecture and contracts
+
+See the in-repo architecture notes for the rebuilt core:
+- Core contracts: [`docs/architecture/core-contracts.md`](docs/architecture/core-contracts.md:1)
+- Architecture overview: [`docs/architecture.md`](docs/architecture.md:1)
+
+Documentation & rescue log
+
+The rescue log contains per-phase notes about the rebuild:
+- [`docs/rescue_log.md`](docs/rescue_log.md:1)
+- Phase G′ (Phase G-prime) documents updated documentation artifacts and
+  provides migration guidance for consumers; see [`docs/migration-guide.md`](docs/migration-guide.md:1).
+
+Contributing
+
+Please follow Conventional Commits for PRs, include tests for contract changes,
+and place towncrier fragments under `newsfragments/` for changelog entries.
+See [`docs/README.md`](docs/README.md:1) for broader documentation contribution
+guidelines.
+
+Tooling
+
+- Pre-commit hooks are configured in [`.pre-commit-config.yaml`](.pre-commit-config.yaml:1).
+- Towncrier configuration is in [`.towncrier.toml`](.towncrier.toml:1).
+
+License & contact
+
+- License: MIT — see [`LICENSE`](LICENSE:1)
+- Contact: project maintainers via repository issues or `press@fba-bench.ai`.
+

fba_bench_core-1.0.0/README.md

@@ -0,0 +1,125 @@
+# FBA-Bench Core — Contract-first Core Library
+
+Overview
+
+FBA-Bench Core is a compact, contract-first library for building and
+simulating Fulfillment-By-Amazon-style (FBA) business automation scenarios.
+The rebuilt core emphasizes explicit, versioned contracts (Pydantic v2 models)
+for domain models, events, commands, and typed configuration objects so
+downstream projects can reliably validate and integrate simulation logic.
+
+Key principles
+
+- Contract-first: canonical Pydantic v2 models are the single source of truth.
+- Typed, immutable configs: configuration objects are frozen models; use
+  model_copy(update={...}) to derive modified instances.
+- Explicit events/commands: typed discriminated unions with strict validation
+  (extra="forbid") to make integration predictable.
+
+Core modules
+
+- Domain models: [`src/fba_bench_core/domain/models.py`](src/fba_bench_core/domain/models.py:1)
+  - Product, InventorySnapshot, CompetitorListing, Competitor, DemandProfile
+- Events & Commands: [`src/fba_bench_core/domain/events.py`](src/fba_bench_core/domain/events.py:1)
+  - Typed BaseEvent/BaseCommand hierarchy and concrete events like SaleOccurred,
+    StockReplenished, PromotionLaunched; commands like AdjustPriceCommand,
+    PlaceReplenishmentOrderCommand.
+- Agent/service base classes: [`src/fba_bench_core/agents/base.py`](src/fba_bench_core/agents/base.py:1)
+  and [`src/fba_bench_core/services/base.py`](src/fba_bench_core/services/base.py:1)
+- Typed configs: [`src/fba_bench_core/config.py`](src/fba_bench_core/config.py:1)
+  - BaseAgentConfig, BaseServiceConfig (immutable, extra="forbid")
+
+Quick start (Poetry)
+
+Clone and install with Poetry:
+
+```bash
+git clone <repo-url>
+cd FBA-Bench-core
+poetry install
+```
+
+Run the test suite:
+
+```bash
+poetry run pytest -q
+```
+
+Using Core from another project
+
+1. Add FBA-Bench Core as a dependency (editable/local for development):
+
+```bash
+pip install -e /path/to/FBA-Bench-core
+```
+
+2. Import domain models and instantiate typed configs:
+
+```python
+from fba_bench_core.domain.models import Product
+from fba_bench_core.config import BaseAgentConfig
+
+p = Product(product_id="sku-1", cost="1.00", price="2.00", stock=10)
+cfg = BaseAgentConfig(agent_id="pricing-agent", poll_interval_seconds=30)
+```
+
+Migration guidance
+
+If you are upgrading from a legacy core:
+- See the migration guide: [`docs/migration-guide.md`](docs/migration-guide.md:1)
+- Key actions: import canonical models, convert numeric values to Decimal,
+  and replace mutable dict-based configs with typed Base*Config models.
+
+Tests, linting and quality commands
+
+The CI pipeline runs formatting, linting, type-checking and tests. Locally you
+can run the same commands via Poetry:
+
+```bash
+poetry run black src tests
+poetry run isort src tests
+poetry run flake8 src tests
+poetry run mypy
+poetry run pytest
+```
+
+Packaging & versioning workflow
+
+- CHANGELOG.md is generated from small towncrier fragments placed under
+  [`newsfragments/`](newsfragments/:1) and built with `towncrier`.
+- To add a changelog fragment: create a brief file `newsfragments/NN.description`
+  then run `poetry run towncrier build --yes`.
+- Version tooling: this repository includes [.bumpver.toml](.bumpver.toml:1)
+  and uses dynamic versioning in the packaging pipeline. Follow project policy
+  for release tagging and bumping; maintainers should prefer automated tools
+  (bumpver) that integrate with CI.
+
+Architecture and contracts
+
+See the in-repo architecture notes for the rebuilt core:
+- Core contracts: [`docs/architecture/core-contracts.md`](docs/architecture/core-contracts.md:1)
+- Architecture overview: [`docs/architecture.md`](docs/architecture.md:1)
+
+Documentation & rescue log
+
+The rescue log contains per-phase notes about the rebuild:
+- [`docs/rescue_log.md`](docs/rescue_log.md:1)
+- Phase G′ (Phase G-prime) documents updated documentation artifacts and
+  provides migration guidance for consumers; see [`docs/migration-guide.md`](docs/migration-guide.md:1).
+
+Contributing
+
+Please follow Conventional Commits for PRs, include tests for contract changes,
+and place towncrier fragments under `newsfragments/` for changelog entries.
+See [`docs/README.md`](docs/README.md:1) for broader documentation contribution
+guidelines.
+
+Tooling
+
+- Pre-commit hooks are configured in [`.pre-commit-config.yaml`](.pre-commit-config.yaml:1).
+- Towncrier configuration is in [`.towncrier.toml`](.towncrier.toml:1).
+
+License & contact
+
+- License: MIT — see [`LICENSE`](LICENSE:1)
+- Contact: project maintainers via repository issues or `press@fba-bench.ai`.

fba_bench_core-1.0.0/pyproject.toml

@@ -0,0 +1,112 @@
+[tool.poetry]
+name = "fba-bench-core"
+version = "1.0.0"
+description = "Core interfaces, data models, and events for the FBA-Bench simulation platform."
+authors = ["FBA Team <devnull@example.com>"]
+license = "Apache-2.0"
+readme = "README.md"
+packages = [{ include = "fba_bench_core", from = "src" }]
+keywords = ["benchmarking", "simulation", "fba", "pydantic", "typing"]
+classifiers = [
+  "Programming Language :: Python :: 3.11",
+  "License :: OSI Approved :: Apache Software License",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+
+[tool.poetry.urls]
+Homepage = "https://github.com/your-org/fba-bench-core"
+Repository = "https://github.com/your-org/fba-bench-core"
+Documentation = "https://your-org.github.io/fba-bench-core"
+Issues = "https://github.com/your-org/fba-bench-core/issues"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+pydantic = "^2.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+pytest-asyncio = "^0.23.0"
+black = "^24.3.0"
+flake8 = "^6.1.0"
+mypy = "^1.8.0"
+pre-commit = "^3.6.0"
+poetry-dynamic-versioning = "^0.19.0"
+towncrier = "^21.0.0"
+bumpver = "^2023.1128"
+pip-audit = "^2.9.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+# --------------------
+# Dynamic versioning
+# --------------------
+[tool.poetry-dynamic-versioning]
+enable = true
+vcs = "git"
+fallback-version = "0.0.0"
+
+# --------------------
+# Towncrier changelog
+# --------------------
+[tool.towncrier]
+package = "fba_bench_core"
+directory = "newsfragments"
+filename = "CHANGELOG.md"
+
+# --------------------
+# Ruff config (linter + import sorter + formatter)
+# --------------------
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+src = ["src"]
+extend-exclude = ["tests/data", "build", "dist"]
+
+[tool.ruff.lint]
+select = ["E", "F", "UP"]
+ignore = ["E501"]
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+known-first-party = ["fba_bench_core"]
+force-single-line = false
+
+# --------------------
+# Black config
+# --------------------
+[tool.black]
+line-length = 88
+target-version = ["py311"]
+skip-string-normalization = true
+
+# --------------------
+# Flake8 config
+# --------------------
+[tool.flake8]
+max-line-length = 88
+extend-ignore = ["E203", "W503"]
+
+# --------------------
+# Mypy config
+# --------------------
+[tool.mypy]
+python_version = "3.11"
+ignore_missing_imports = true
+pretty = true
+warn_unused_ignores = true
+files = ["src/fba_bench_core", "tests"]
+
+# --------------------
+# Pytest config
+# --------------------
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra --cov=src/fba_bench_core --cov-report=term-missing --cov-report=html"
+testpaths = ["tests"]
+asyncio_mode = "auto"

fba_bench_core-1.0.0/src/fba_bench_core/__init__.py

@@ -0,0 +1,11 @@
+"""Phase 2 scaffold for the fba_bench_core package.
+
+This module is a minimal placeholder created during Phase 2 of the
+core rebuild. It intentionally contains no runtime logic; only the
+package-level metadata required to allow safe imports and satisfy
+linters during the rescue process.
+"""
+
+__all__ = []
+
+__version__ = "1.0.0"

fba_bench_core-1.0.0/src/fba_bench_core/agents/__init__.py

@@ -0,0 +1,15 @@
+"""Package exports for fba_bench_core.agents.
+
+Exports the BaseAgent abstract class and exposes the registry module to allow
+external code to discover and register agent implementations. Also export the
+typed base configuration model to make it easy for downstream users to extend.
+"""
+
+from __future__ import annotations
+
+from fba_bench_core.config import BaseAgentConfig
+
+from . import registry
+from .base import BaseAgent
+
+__all__ = ["BaseAgent", "registry", "BaseAgentConfig"]

fba_bench_core-1.0.0/src/fba_bench_core/agents/base.py

@@ -0,0 +1,83 @@
+"""Typed BaseAgent for fba_bench_core.
+
+Phase D change:
+- Replace legacy **kwargs configuration with a typed Pydantic configuration
+  object. Downstream implementations should subclass the provided config model
+  for specialized parameters.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from fba_bench_core.config import BaseAgentConfig
+from fba_bench_core.domain.events import BaseEvent, Command
+
+
+class BaseAgent(ABC):
+    """Abstract base class for agents that receive a validated configuration.
+
+    Rationale:
+        Using a typed configuration object prevents downstream implementations
+        from hiding untyped parameters behind `Any` and enables validation at
+        construction time. Implementations that require additional fields may
+        subclass `BaseAgentConfig` (see examples in the config module).
+
+    Initialization:
+        The agent receives a single `config: BaseAgentConfig` argument. The
+        `agent_id` is expected to be present on that config and becomes the
+        agent's immutable identifier.
+
+    Immutability:
+        The provided config model is frozen (Pydantic frozen model). The agent
+        stores the config object directly and exposes it via a read-only
+        property to avoid accidental mutation.
+    """
+
+    def __init__(self, config: BaseAgentConfig) -> None:
+        """Initialize the base agent with a validated, typed configuration.
+
+        Parameters:
+            config: An instance of BaseAgentConfig or a subclass thereof. The
+                    model is validated by Pydantic prior to construction.
+
+        Notes:
+            - Do not accept `**kwargs` here: typed configs are required.
+            - The agent keeps a reference to the provided config (which is
+              immutable/frozen). Use `agent.config.model_copy()` to obtain a
+              mutable copy if necessary.
+        """
+        self._config = config
+        self._agent_id = config.agent_id
+
+    @property
+    def agent_id(self) -> str:
+        """Return the agent's unique identifier (from config.agent_id)."""
+        return self._agent_id
+
+    @property
+    def config(self) -> BaseAgentConfig:
+        """Return the typed configuration object for this agent.
+
+        The returned object is immutable (Pydantic frozen model). Downstream
+        code that needs to modify configuration should create a new instance
+        (e.g., via `model_copy(update={...})`).
+        """
+        return self._config
+
+    def get_config(self) -> dict:
+        """Return a serializable shallow mapping of the configuration.
+
+        Returns:
+            A dict produced by Pydantic's model_dump() representing the config.
+        """
+        return self._config.model_dump()
+
+    @abstractmethod
+    async def decide(self, events: list[BaseEvent]) -> list[Command]:
+        """Decide on a list of Commands given observed domain events.
+
+        Implementations must be async coroutines and must not mutate the
+        provided `events` list.
+        """
+        raise NotImplementedError

fba_bench_core-1.0.0/src/fba_bench_core/agents/registry.py

@@ -0,0 +1,16 @@
+"""Phase 5 placeholder for the agent registry.
+
+This module will hold mappings of agent names to agent classes and will be
+populated during Phase 5. It intentionally contains no runtime logic now.
+"""
+
+AGENT_REGISTRY: dict[str, type] = {}  # Populated in a later phase (Phase 5)
+
+
+def create_runner(key: str, config: dict):
+    """Stub function for creating runners."""
+
+    class DummyRunner:
+        agent_id = config.get("agent_id", "dummy")
+
+    return DummyRunner()

fba_bench_core-1.0.0/src/fba_bench_core/benchmarking/__init__.py

@@ -0,0 +1,6 @@
+"""Benchmarking module for FBA Bench Core.
+
+This module provides benchmarking functionality including engine, scenarios, metrics, and validators.
+"""
+
+__all__ = []

fba_bench_core-1.0.0/src/fba_bench_core/benchmarking/core/__init__.py

@@ -0,0 +1 @@
+# Benchmarking core module

fba_bench_core-1.0.0/src/fba_bench_core/benchmarking/engine/__init__.py

@@ -0,0 +1,12 @@
+"""Public API for the FBA-Bench Benchmarking Engine."""
+
+from .core import Engine
+from .models import EngineConfig, EngineReport, RunnerSpec, ScenarioSpec
+
+__all__ = [
+    "Engine",
+    "EngineConfig",
+    "EngineReport",
+    "RunnerSpec",
+    "ScenarioSpec",
+]