Metadata-Version: 2.4
Name: tucoopy
Version: 0.1.0
Summary: Cooperative game theory (TU) algorithms + animation spec generator
Author: Brenno Gustavo Barbosa
License: MIT License
        
        Copyright (c) 2026 tucoopy contributors
        
        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.
        
        
Project-URL: Homepage, https://github.com/brennobarbosa/tucoopy
Project-URL: Repository, https://github.com/brennobarbosa/tucoopy
Project-URL: Issues, https://github.com/brennobarbosa/tucoopy/issues
Keywords: cooperative-game-theory,game-theory,shapley,banzhaf,nucleolus
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: lp
Requires-Dist: scipy>=1.10; extra == "lp"
Provides-Extra: lp-alt
Requires-Dist: pulp>=2.8; extra == "lp-alt"
Provides-Extra: fast
Requires-Dist: numpy>=1.26; extra == "fast"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8; extra == "viz"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
Requires-Dist: griffe>=0.49; extra == "docs"
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.5; extra == "docs"
Requires-Dist: mkdocs-minify-plugin>=0.8; extra == "docs"
Requires-Dist: mkdocs-awesome-pages-plugin>=2.10; extra == "docs"
Requires-Dist: ruff>=0.15; extra == "docs"
Dynamic: license-file

# tucoopy-py

Python package for cooperative game theory (TU) algorithms and for generating
animation specs (JSON) consumed by the JS renderer.

Optional speedups:
- `pip install "tucoopy[fast]"` (uses NumPy for small linear solves in geometry helpers)
- `pip install "tucoopy[lp]"` (enables LP-based methods like least-core / nucleolus via SciPy)

Optional visualization:
- `pip install "tucoopy[viz]"` for Matplotlib visualization (2 or 3 players only)

## Optional extras (feature -> extra)

| Feature | Extra | Notes |
| --- | --- | --- |
| LP-backed methods | `lp` | SciPy backend (recommended) |
| LP-backed methods (fallback) | `lp_alt` | PuLP backend |
| Speedups | `fast` | NumPy helper routines |
| Static visualization | `viz` | Matplotlib (2 or 3 players only) |
| Dev tools | `dev` | pytest + mypy + ruff |
| Docs build | `docs` | mkdocs + mkdocstrings |

## Package layout

- `tucoopy.base`: game/coalition primitives (bitmask-based)
- `tucoopy.properties`: game properties / recognizers
- `tucoopy.games`: classic games (glove, weighted voting, airport, bankruptcy, savings, unanimity, apex, ...)
- `tucoopy.geometry`: geometry for visualization (core vertices, ...)
- `tucoopy.solutions`: solution concepts (Shapley, Banzhaf, ...)
- `tucoopy.power`: voting/simple-game power indices
- `tucoopy.transforms`: transforms/representations (Harsanyi dividends, ...)
- `tucoopy.viz`: optional visualization with Matplotlib (games with 2 or 3 players only)
- `tucoopy.io`: JSON + animation spec helpers
- `tucoopy.backends`: adapters for optional dependencies (LP, NumPy, ...)

Docs (in this repo): see `packages/tucoopy-py/docs/en/index.md` (EN) and `packages/tucoopy-py/docs/pt/index.md` (PT).
Examples (runnable scripts): see `packages/tucoopy-py/examples/README.md`.

## Install

```bash
pip install tucoopy
```

Optional extras:

- `pip install "tucoopy[lp]"` for LP-based methods (least-core / nucleolus / modiclus / balancedness) using SciPy (recommended)
- `pip install "tucoopy[lp_alt]"` for LP-based methods (least-core / nucleolus / modiclus / balancedness) using PuLP (fallback)
- `pip install "tucoopy[fast]"` for NumPy speedups (kernel / prekernel and helpers)
- `pip install "tucoopy[viz]"` for Matplotlib visualization (2 or 3 players only)

## Quick example (generate an animation spec)

```py
from tucoopy import Game
from tucoopy.solutions import shapley_value
from tucoopy.io.animation_spec import build_animation_spec

game = Game.from_coalitions(
    n_players=3,
    values={
        (): 0.0,
        (0,): 1.0,
        (1,): 1.2,
        (2,): 0.8,
        (0, 1): 2.8,
        (0, 2): 2.2,
        (1, 2): 2.0,
        (0, 1, 2): 4.0,
    },
    player_labels=["P1", "P2", "P3"],
)

phi = shapley_value(game)
spec = build_animation_spec(
    game,
    series_id="shapley",
    allocations=[phi] * 60,
    dt=1 / 30,
    series_description="Shapley value (static).",
    include_analysis=True,
)
print(spec.to_json())
```

## Nucleolus / least-core (LP)

LP-based methods are behind the optional `lp` extra:

```py
from tucoopy import Game
from tucoopy.solutions import least_core, nucleolus

g = Game.from_coalitions(
    n_players=3,
    values={
        (): 0.0,
        (0,): 1.0,
        (1,): 1.2,
        (2,): 0.8,
        (0, 1): 2.8,
        (0, 2): 2.2,
        (1, 2): 2.0,
        (0, 1, 2): 4.0,
    },
)

lc = least_core(g)
nu = nucleolus(g)
print(lc.epsilon, lc.x)
print(nu.levels, nu.x)
```

## Core non-emptiness certificate (LP)

Bondareva–Shapley balancedness check (behind `lp`):

```py
from tucoopy import Game
from tucoopy.properties.balancedness import balancedness_check

g = Game.from_coalitions(
    n_players=3,
    values={
        (): 0.0,
        (0,): 0.0,
        (1,): 0.0,
        (2,): 0.0,
        (0, 1): 1.0,
        (0, 2): 1.0,
        (1, 2): 1.0,
        (0, 1, 2): 1.0,
    },
)

res = balancedness_check(g)
print(res.core_nonempty, res.objective, res.weights)
```

## Schema (Python <-> JS contract)

- Canonical schema: `schema/tucoopy-animation.schema.json`
- Bundled schema (package data): `packages/tucoopy-py/src/tucoopy/io/schemas/tucoopy-animation.schema.json`
