# open-games-spec

Typed DSL for compositional game theory, built on [gds-framework](https://github.com/BlockScience/gds-framework).

## What is this?

`open-games-spec` extends the GDS framework with game-theoretic vocabulary — open games, strategic interactions, and compositional game patterns. It provides:

- **6 atomic game types** — Decision, CovariantFunction, ContravariantFunction, FeedbackGame, CorecursiveGame, IdentityGame
- **Pattern composition** — Sequential, Parallel, Feedback, and Corecursive composition operators
- **IR compilation** — Flatten game patterns into JSON-serializable intermediate representation
- **13 verification checks** — Type matching (T-001..T-006) and structural validation (S-001..S-007)
- **7 Markdown report templates** — System overview, verification summary, state machine, interface contracts, and more
- **6 Mermaid diagram generators** — Structural, hierarchy, flow topology, architecture views
- **CLI** — `ogs compile`, `ogs verify`, `ogs report`

## Architecture

```
gds-framework (pip install gds-framework)
│
│  Domain-neutral composition algebra, typed spaces,
│  state model, verification engine, flat IR compiler.
│
└── open-games-spec (pip install open-games-spec)
    │
    │  Game-theoretic DSL: OpenGame types, Pattern composition,
    │  compile_to_ir(), domain verification, reports, visualization.
    │
    └── Your application
        │
        │  Concrete pattern definitions, analysis notebooks,
        │  verification runners.
```

## Quick start

```bash
pip install open-games-spec
```

```python
from ogs.dsl.games import Decision, CovariantFunction
from ogs.dsl.composition import Flow
from ogs.dsl.pattern import Pattern
from ogs.dsl.compile import compile_to_ir
from ogs import verify

# Define games
sensor = CovariantFunction(name="Sensor", x="observation", y="signal")
agent = Decision(name="Agent", x="signal", y="action", r="reward", s="experience")

# Compose into a pattern
pattern = Pattern(
    name="Simple Decision",
    games=[sensor, agent],
    flows=[Flow(source="Sensor", target="Agent", label="signal")],
)

# Compile and verify
ir_doc = compile_to_ir(pattern)
report = verify(ir_doc)
print(f"{report.checks_passed}/{report.checks_total} checks passed")
```

## License

Apache-2.0

## Credits & Attribution

### Development & Implementation
* **Primary Author:** [Rohan Mehta](mailto:rohan@block.science)
* **Organization:** [BlockScience](https://block.science/)

### Theoretical Foundation
This codebase is a direct implementation of the research and mathematical frameworks developed by:
* **Dr. Jamsheed Shorish** ([@jshorish](https://github.com/jshorish)) and **Dr. Michael Zargham** ([@mzargham](https://github.com/mzargham)).
* **Key Reference:** [Generalized Dynamical Systems, Part I: Foundations](https://blog.block.science/generalized-dynamical-systems-part-i-foundations-2/) (BlockScience, 2021).

### Architectural Inspiration
The design patterns and structural approach of this library are heavily influenced by the prior work of **Sean McOwen** ([@SeanMcOwen](https://github.com/SeanMcOwen)), specifically:
* [MSML](https://github.com/BlockScience/MSML): For system specification logic.
* [bdp-lib](https://github.com/BlockScience/bdp-lib): For block-data processing architecture.

### Contributors
* **Peter Hacker** ([@phacker3](https://github.com/phacker3)) — Code auditing and review (BlockScience).

### Intellectual Lineage
This project exists within the broader ecosystem of:
* [cadCAD](https://github.com/cadCAD-org/cadCAD): For foundational philosophy in Complex Adaptive Dynamics.
