Metadata-Version: 2.5
Name: entirius-django-pricefighter
Version: 1.1.0
Summary: Competitive pricing module for Entirius: strategies, price decisions from market observations, apply and audit
Project-URL: Homepage, https://docs.entirius.com/
Project-URL: Documentation, https://github.com/entirius/entirius-django-pricefighter/tree/develop/docs
Project-URL: Repository, https://github.com/entirius/entirius-django-pricefighter
Project-URL: Changelog, https://github.com/entirius/entirius-django-pricefighter/blob/develop/CHANGELOG.md
Project-URL: Issues, https://github.com/entirius/entirius-django-pricefighter/issues
Author: Entirius
Maintainer-email: Piotr Brzozowski <piotrb@entirius.com>, Paweł Kiełt <cptshooter12@gmail.com>, Mateusz Baran <mateuszbaranpv@gmail.com>, Michał Kloczkowski <michal@kloczkowski.pl>
License-Expression: MPL-2.0
License-File: LICENSE
Keywords: django,ecommerce,entirius,price-monitoring,pricing,repricing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.11
Requires-Dist: celery>=5.3
Requires-Dist: django>=5.0
Requires-Dist: djangorestframework-simplejwt>=5.3
Requires-Dist: djangorestframework>=3.14
Requires-Dist: drf-spectacular>=0.27
Requires-Dist: entirius-django-atlas>=2.0.0
Requires-Dist: entirius-django-pricemanager>=4.2.0
Requires-Dist: entirius-django-regional>=2.0.1
Requires-Dist: entirius-django-utils>=2.0.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: pim
Requires-Dist: entirius-django-pim>=3.0.0; extra == 'pim'
Provides-Extra: test
Requires-Dist: dj-database-url; extra == 'test'
Requires-Dist: entirius-django-pim>=3.0.0; extra == 'test'
Requires-Dist: psycopg[binary]; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-django; extra == 'test'
Description-Content-Type: text/markdown

# entirius-django-pricefighter

A Django module for competitive pricing in Entirius, the open-source modular ecommerce platform.
It compares each product's price with competitor observations per market, recommends a new price under a pricing
strategy, and applies approved decisions through the price module with a full audit snapshot.

[![PyPI](https://img.shields.io/pypi/v/entirius-django-pricefighter.svg)](https://pypi.org/project/entirius-django-pricefighter/)
[![Python](https://img.shields.io/pypi/pyversions/entirius-django-pricefighter.svg)](https://pypi.org/project/entirius-django-pricefighter/)
[![License: MPL-2.0](https://img.shields.io/badge/license-MPL--2.0-blue.svg)](https://github.com/entirius/entirius-django-pricefighter/blob/develop/LICENSE)

## What it does

- Mirrors catalog products per sales channel and keeps the mirror in sync (signals and a daily full sync).
- Resolves a pricing strategy per product and market (`hold`, `compete`, `raise`), most specific rule first.
- Computes a decision view: gap to the competitor reference price, a recommendation and a suggested price,
  within floor, ceiling and step limits.
- Applies an approved decision through the price module and logs a `PriceDecision` snapshot of every input.
- Exposes an admin API (JWT, Pydantic schemas, OpenAPI): channels, decisions, bounds, history, apply, rules.

## Installation

```shell
uv add entirius-django-pricefighter
pip install entirius-django-pricefighter
```

Optional extras: `entirius-django-pricefighter[pim]` (product sync from the catalog module; without it the sync
does nothing).

```python
INSTALLED_APPS = [
    ...
    "django_utils",
    "django_regional",
    "django_pricemanager",
    "django_atlas",
    "django_pricefighter",
]

# urls.py
urlpatterns = [
    path("", include("django_pricefighter.urls")),
]
```

Optional settings: `PRICEFIGHTER_REF_ESTIMATOR`, `PRICEFIGHTER_STALENESS_DAYS`,
`PRICEFIGHTER_DECISION_RETENTION_DAYS`; reference with defaults in
https://github.com/entirius/entirius-django-pricefighter/blob/develop/AGENTS.md (section Settings).

## Quick start

```python
from django_pricefighter.services.decision_view_service import build_decision_rows

# decision rows for every product with a fresh competitor observation, largest gap first
rows, total = build_decision_rows(sort="-gap_baseline", limit=50)
```

```shell
python manage.py sync_pricefighter_channels
python manage.py pricefighter_full_sync
```

## Requirements

- Python 3.11 or newer, Django 5.0 or newer, PostgreSQL, a Celery worker for the sync and retention tasks.
- Entirius packages pulled in: `entirius-django-utils`, `entirius-django-regional`,
  `entirius-django-pricemanager`, `entirius-django-atlas`.

## Documentation

- Data model: https://github.com/entirius/entirius-django-pricefighter/blob/develop/docs/data-model.md
- Sync from the catalog: https://github.com/entirius/entirius-django-pricefighter/blob/develop/docs/sync.md
- Strategy resolution: https://github.com/entirius/entirius-django-pricefighter/blob/develop/docs/strategy-resolution.md
- Decision engine: https://github.com/entirius/entirius-django-pricefighter/blob/develop/docs/decision-engine.md
- Apply flow: https://github.com/entirius/entirius-django-pricefighter/blob/develop/docs/apply-flow.md
- Admin API: https://github.com/entirius/entirius-django-pricefighter/blob/develop/docs/api.md
- Gotchas: https://github.com/entirius/entirius-django-pricefighter/blob/develop/docs/gotchas.md
- Testing: https://github.com/entirius/entirius-django-pricefighter/blob/develop/docs/testing.md
- Entirius documentation: https://docs.entirius.com/
- Changelog: https://github.com/entirius/entirius-django-pricefighter/blob/develop/CHANGELOG.md

## Part of Entirius

This module runs inside the Entirius backend service (Volkanos); it reads competitor observations from the
external product data engine and writes prices through the price module.

- Backend service: https://github.com/entirius/entirius-service-volkanos
- Docker harness: https://github.com/entirius/entirius-zeno
- Sibling modules: https://github.com/entirius/entirius-django-atlas, https://github.com/entirius/entirius-django-pricemanager,
  https://github.com/entirius/entirius-django-pim

## Development

```shell
make install     # sync dependencies (uv, incl. extras)
make check       # lint + format check (ruff)
make test        # test suite (pytest + pytest-django, needs PostgreSQL via DATABASE_URL)
```

Development and agent instructions: https://github.com/entirius/entirius-django-pricefighter/blob/develop/AGENTS.md

## License

Mozilla Public License 2.0 (MPL-2.0) — see https://github.com/entirius/entirius-django-pricefighter/blob/develop/LICENSE.
