bambon 1.0.0__tar.gz

bambon-1.0.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: bambon
+Version: 1.0.0
+Summary: An SDK to suppoort automated ODRL-policy negotiation.
+Home-page: https://github.com/isotiropoulos/BayesianNegotiator
+Author-email: Iason Sotiropoulos <isotiropoulos@singularlogic.eu>
+Project-URL: Homepage, https://github.com/isotiropoulos/BayesianNegotiator
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.7.0
+Dynamic: home-page
+
+# Bambon Negotiator
+
+**Bambon** (*Bayesian Adaptive Mixed-type Bilateral ODRL-policy Negotiator*) is a learning-based negotiator for **negotiating constraints over one or multiple actions** (e.g., `use`, `read`, `share`, `transfer`) expressed in an **ODRL-style policy format**.
+
+Bambon observes opponent offers, updates Bayesian beliefs about opponent preferences (numeric / enum / set issues), and generates counter-offers until:
+- agreement is reached (`odrl:Agreement`), or
+- the negotiation becomes infeasible (`NegotiationInfeasible`)
+
+---
+
+## Features
+
+- ✅ Negotiates **constraints per action** (single-action or multi-action offers)
+- ✅ Supports **mixed-type issues**:
+  - numeric constraints
+  - categorical/enum constraints
+  - set-valued constraints
+- ✅ Bayesian belief models to learn opponent preferences over time
+- ✅ Hard policy enforcement (non-negotiable constraints)
+- ✅ Context similarity & severity scoring
+- ✅ Hopelessness detection (fails fast if negotiation diverges)
+
+---
+
+## Repository Structure
+
+- `negotiator.py`  
+  Main implementation: `Bambon` (observe / counter-offer / agreement logic)
+
+- `belief.py`  
+  `BeliefRegistry` manages belief models per action & issue
+
+- `distributions.py`  
+  Bayesian belief distributions:
+  - numeric beta-based model
+  - Dirichlet model for categorical constraints
+  - set belief handling
+
+- `models.py`  
+  Core dataclasses and `NegotiationInfeasible` exception
+
+- `helpers.py`  
+  Constraint parsing + operator helpers
+
+- `context.py`  
+  Similarity + severity scoring
+
+- `expressions.py`  
+  Expression helpers for constraints
+
+- `test_negotiator.py`  
+  Negotiation simulations / profiles (balanced, aggressive, exploratory)
+
+---
+
+## Offer Format (ODRL-style)
+
+Bambon expects offers in an ODRL-like JSON format:
+
+```json
+{
+  "@id": "urn:uid:example",
+  "@type": "odrl:Offer",
+  "permission": [
+    {
+      "action": "use",
+      "constraint": [
+        {
+          "leftOperand": "odrl:purpose",
+          "operator": "odrl:eq",
+          "rightOperand": "research"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Constraints are normalized internally (e.g., `odrl:` prefixes stripped during parsing).
+
+---
+
+## Quickstart
+
+### 1) Create a negotiator
+
+```python
+from negotiator import Bambon
+
+neg = Bambon(
+    name="Provider",
+    init_offer=init_offer,        # required
+    hard_policy=hard_policy       # optional
+)
+```
+
+Each action in `init_offer["permission"]` gets its own:
+- belief registry
+- negotiation state
+
+---
+
+### 2) Observe an opponent offer and generate a response
+
+```python
+signals, response_offer = neg.observe(opponent_offer)
+
+print("Signals:", signals)
+print("Response:", response_offer)
+```
+
+- `signals` is `None` while negotiating
+- `signals` becomes non-null when an action is accepted and agreement is formed
+- `response_offer` will be either:
+  - a counter-offer (`odrl:Offer`), or
+  - an agreement (`odrl:Agreement`)
+
+---
+
+## Running
+
+### Run tests (recommended)
+
+```bash
+pytest -q
+```
+
+or:
+
+```bash
+python -m unittest -v
+```
+
+---
+
+## Example Minimal Negotiation Loop
+
+```python
+from negotiator import Bambon
+
+provider = Bambon(name="Provider", init_offer=provider_init, hard_policy=provider_hard)
+consumer = Bambon(name="Consumer", init_offer=consumer_init)
+
+offer = consumer_init
+for round_i in range(50):
+    sig_p, offer = provider.observe(offer)
+    if offer.get("@type") == "odrl:Agreement":
+        print("Agreement reached (provider -> consumer)")
+        break
+
+    sig_c, offer = consumer.observe(offer)
+    if offer.get("@type") == "odrl:Agreement":
+        print("Agreement reached (consumer -> provider)")
+        break
+else:
+    print("No agreement reached within max rounds")
+```
+
+---
+
+## Key Negotiation Parameters
+
+Bambon behavior is governed by tunable controls, including:
+
+- `lr` — learning rate for belief updates
+- `inertia` — resistance to changing past proposals
+- `tau_in`, `tau_out` — thresholds controlling adaptation vs acceptance
+- `max_set_k` — maximum size for proposed sets
+- `jaccard_snap_threshold` — snaps set proposals when overlap is high
+- `no_agreement_until` — prevents early agreement before minimum rounds
+- `max_rounds` — maximum rounds before infeasibility
+- `hopeless_window`, `hopeless_patience` — detects non-converging negotiation
+
+If negotiation is judged impossible, Bambon raises:
+
+```python
+from models import NegotiationInfeasible
+```
+
+---
+
+## Output Types
+
+Bambon produces ODRL-like structures:
+
+- **Counter-offer**: `@type = "odrl:Offer"`
+- **Agreement**: `@type = "odrl:Agreement"` with constraints filled using accepted values
+
+---

bambon-1.0.0/README.md

@@ -0,0 +1,189 @@
+# Bambon Negotiator
+
+**Bambon** (*Bayesian Adaptive Mixed-type Bilateral ODRL-policy Negotiator*) is a learning-based negotiator for **negotiating constraints over one or multiple actions** (e.g., `use`, `read`, `share`, `transfer`) expressed in an **ODRL-style policy format**.
+
+Bambon observes opponent offers, updates Bayesian beliefs about opponent preferences (numeric / enum / set issues), and generates counter-offers until:
+- agreement is reached (`odrl:Agreement`), or
+- the negotiation becomes infeasible (`NegotiationInfeasible`)
+
+---
+
+## Features
+
+- ✅ Negotiates **constraints per action** (single-action or multi-action offers)
+- ✅ Supports **mixed-type issues**:
+  - numeric constraints
+  - categorical/enum constraints
+  - set-valued constraints
+- ✅ Bayesian belief models to learn opponent preferences over time
+- ✅ Hard policy enforcement (non-negotiable constraints)
+- ✅ Context similarity & severity scoring
+- ✅ Hopelessness detection (fails fast if negotiation diverges)
+
+---
+
+## Repository Structure
+
+- `negotiator.py`  
+  Main implementation: `Bambon` (observe / counter-offer / agreement logic)
+
+- `belief.py`  
+  `BeliefRegistry` manages belief models per action & issue
+
+- `distributions.py`  
+  Bayesian belief distributions:
+  - numeric beta-based model
+  - Dirichlet model for categorical constraints
+  - set belief handling
+
+- `models.py`  
+  Core dataclasses and `NegotiationInfeasible` exception
+
+- `helpers.py`  
+  Constraint parsing + operator helpers
+
+- `context.py`  
+  Similarity + severity scoring
+
+- `expressions.py`  
+  Expression helpers for constraints
+
+- `test_negotiator.py`  
+  Negotiation simulations / profiles (balanced, aggressive, exploratory)
+
+---
+
+## Offer Format (ODRL-style)
+
+Bambon expects offers in an ODRL-like JSON format:
+
+```json
+{
+  "@id": "urn:uid:example",
+  "@type": "odrl:Offer",
+  "permission": [
+    {
+      "action": "use",
+      "constraint": [
+        {
+          "leftOperand": "odrl:purpose",
+          "operator": "odrl:eq",
+          "rightOperand": "research"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Constraints are normalized internally (e.g., `odrl:` prefixes stripped during parsing).
+
+---
+
+## Quickstart
+
+### 1) Create a negotiator
+
+```python
+from negotiator import Bambon
+
+neg = Bambon(
+    name="Provider",
+    init_offer=init_offer,        # required
+    hard_policy=hard_policy       # optional
+)
+```
+
+Each action in `init_offer["permission"]` gets its own:
+- belief registry
+- negotiation state
+
+---
+
+### 2) Observe an opponent offer and generate a response
+
+```python
+signals, response_offer = neg.observe(opponent_offer)
+
+print("Signals:", signals)
+print("Response:", response_offer)
+```
+
+- `signals` is `None` while negotiating
+- `signals` becomes non-null when an action is accepted and agreement is formed
+- `response_offer` will be either:
+  - a counter-offer (`odrl:Offer`), or
+  - an agreement (`odrl:Agreement`)
+
+---
+
+## Running
+
+### Run tests (recommended)
+
+```bash
+pytest -q
+```
+
+or:
+
+```bash
+python -m unittest -v
+```
+
+---
+
+## Example Minimal Negotiation Loop
+
+```python
+from negotiator import Bambon
+
+provider = Bambon(name="Provider", init_offer=provider_init, hard_policy=provider_hard)
+consumer = Bambon(name="Consumer", init_offer=consumer_init)
+
+offer = consumer_init
+for round_i in range(50):
+    sig_p, offer = provider.observe(offer)
+    if offer.get("@type") == "odrl:Agreement":
+        print("Agreement reached (provider -> consumer)")
+        break
+
+    sig_c, offer = consumer.observe(offer)
+    if offer.get("@type") == "odrl:Agreement":
+        print("Agreement reached (consumer -> provider)")
+        break
+else:
+    print("No agreement reached within max rounds")
+```
+
+---
+
+## Key Negotiation Parameters
+
+Bambon behavior is governed by tunable controls, including:
+
+- `lr` — learning rate for belief updates
+- `inertia` — resistance to changing past proposals
+- `tau_in`, `tau_out` — thresholds controlling adaptation vs acceptance
+- `max_set_k` — maximum size for proposed sets
+- `jaccard_snap_threshold` — snaps set proposals when overlap is high
+- `no_agreement_until` — prevents early agreement before minimum rounds
+- `max_rounds` — maximum rounds before infeasibility
+- `hopeless_window`, `hopeless_patience` — detects non-converging negotiation
+
+If negotiation is judged impossible, Bambon raises:
+
+```python
+from models import NegotiationInfeasible
+```
+
+---
+
+## Output Types
+
+Bambon produces ODRL-like structures:
+
+- **Counter-offer**: `@type = "odrl:Offer"`
+- **Agreement**: `@type = "odrl:Agreement"` with constraints filled using accepted values
+
+---

bambon-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bambon"
+version = "1.0.0"
+authors = [
+  { name="Iason Sotiropoulos", email="isotiropoulos@singularlogic.eu"},
+]
+dependencies = [
+    "pydantic>=2.7.0"
+]
+
+description = "An SDK to suppoort automated ODRL-policy negotiation."
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+#
+[project.urls]
+Homepage = "https://github.com/isotiropoulos/BayesianNegotiator"
+#Issues = "https://github.com/pypa/sampleproject/issues"

bambon-1.0.0/setup.cfg

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

bambon-1.0.0/setup.py

@@ -0,0 +1,17 @@
+from setuptools import setup, find_packages
+from os import path
+
+working_directory = path.abspath(path.dirname(__file__))
+
+with open(path.join(working_directory, 'README.md'), encoding='utf-8') as f:
+    long_description = f.read()
+
+setup(
+    name='bambon', # name of packe which will be package dir below project
+    url='https://github.com/isotiropoulos/BayesianNegotiator',
+    long_description=long_description,
+    long_description_content_type='text/markdown',
+    packages=find_packages('src'),
+    package_dir={'': 'src'},
+    zip_safe=False
+)