Metadata-Version: 2.4
Name: normsync
Version: 0.1.1
Summary: World constitution engine for norm-governed multi-agent games
Project-URL: Homepage, https://github.com/sandeep-alluru/normsync
Project-URL: Repository, https://github.com/sandeep-alluru/normsync
Project-URL: Documentation, https://sandeep-alluru.github.io/normsync
Project-URL: Changelog, https://github.com/sandeep-alluru/normsync/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/sandeep-alluru/normsync/issues
Author-email: Sandeep Alluru <onepuncchh@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Sandeep Alluru
        
        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.
License-File: LICENSE
Keywords: agents,ai-alignment,gaming,governance,llm,llmops,mcp,multi-agent,norms,simulation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == 'api'
Requires-Dist: uvicorn>=0.29; extra == 'api'
Provides-Extra: dev
Requires-Dist: fastapi>=0.110; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# normsync

**World constitution engine for norm-governed multi-agent games.**

![normsync](assets/hero.png)

[![CI](https://github.com/sandeep-alluru/normsync/actions/workflows/ci.yml/badge.svg)](https://github.com/sandeep-alluru/normsync/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/normsync.svg)](https://pypi.org/project/normsync/)
[![Python 3.10+](https://img.shields.io/pypi/pyversions/normsync.svg)](https://pypi.org/project/normsync/)
[![Downloads](https://img.shields.io/pypi/dm/normsync.svg)](https://pypi.org/project/normsync/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![codecov](https://codecov.io/gh/sandeep-alluru/normsync/branch/main/graph/badge.svg)](https://codecov.io/gh/sandeep-alluru/normsync)
[![Typed](https://img.shields.io/badge/types-mypy-blue)](https://mypy-lang.org/)

[Quick Start](#quick-start) · [How It Works](#how-it-works) · [CLI Reference](#cli-reference) · [GitHub Action](#github-action) · [vs. Alternatives](#vs-alternatives) · [Contributing](CONTRIBUTING.md)

---

## Why

Multi-agent simulations and games need rules. But rules encoded in agent logic become invisible, hard to audit, and impossible to update without redeploying every agent.

normsync solves this by providing a **world constitution engine**: a centralized, content-addressed registry of normative rules that any agent can query. When an agent takes an action, normsync checks it against the active constitution and emits violations. Rules can be added, modified, or repealed at runtime without touching agent code.

```
normsync check agent1 attack safe_zone   # Fails if "attack in safe_zone" is prohibited
```

This is especially powerful in:
- **AI safety research**: enforce behavioral constraints in multi-agent simulations
- **Game design**: codify win conditions, prohibited actions, and faction rules
- **LLM agent governance**: define and monitor behavioral policies for AI agents
- **Compliance testing**: record which agent violated which rule and when

---

## How It Works

```mermaid
flowchart LR
    A[Define WorldNorm\nname · condition · prohibited] --> B[NormStore\nSQLite backend]
    B --> C[NormMonitor\nloads active norms]
    C --> D[AgentAction\nagent_id · action · location]
    D --> E{Condition matches\nprohibited matches?}
    E -->|Yes| F[NormViolation\nstored + emitted]
    E -->|No| G[Action allowed]
    F --> H[Report\nJSON · Markdown · Rich table]
```

**Core primitives:**

- **WorldNorm** — a rule with a `condition` (when it applies) and a `prohibited` (what is forbidden). ID = SHA-256[:16] of `name|condition|prohibited`. Two agents defining the same rule always get the same ID.
- **AgentAction** — a timestamped action taken by an agent with `agent_id`, `action`, `location`, `target`, and `faction`.
- **NormViolation** — emitted when an action matches both the condition and prohibited token of an active norm.
- **NormRevision** — records when a norm is created, modified, or repealed.

Matching is token-based and case-insensitive: condition tokens must appear in the action's fields, and the prohibited token must match the action verb.

---

## Features

| Feature | Details |
|---------|---------|
| Content-addressed norms | SHA-256[:16] of name\|condition\|prohibited — same rule always same ID |
| Token-based matching | Case-insensitive, split on whitespace — no regex needed |
| Norm lifecycle | Add, repeal, and query active norms at runtime |
| SQLite persistence | Single file, no server required |
| In-memory mode | `NormStore(":memory:")` for testing and ephemeral sessions |
| REST API | `/norm`, `/norms`, `/check`, `/violations`, `/health` endpoints |
| MCP server | Model Context Protocol tools for Claude and other agents |
| CLI | `normsync add`, `check`, `violations`, `revisions`, `status` |
| JSON output | Machine-readable reports for downstream automation |
| Markdown output | Ready-to-paste GitHub PR comments |
| 118 tests | Comprehensive test suite covering all layers |

---

## Quick Start

```bash
pip install normsync
```

```python
from normsync import NormMonitor, WorldNorm, AgentAction, print_violations

# Define world norms
monitor = NormMonitor()
monitor.add_norm(WorldNorm(
    name="no-attack-in-safe-zone",
    description="Attacking is prohibited in safe zones",
    condition="safe_zone",
    prohibited="attack",
))

# Check agent actions
action = AgentAction("hero", "attack", "safe_zone")
violations = monitor.check(action)

print_violations(violations)
# → Norm Violations table: hero | no-attack-in-safe-zone | ...

# Repeal a norm at runtime
monitor.repeal_norm(monitor.active_norms()[0].id)
```

**With SQLite persistence** — use `NormStore` to persist norms and violations across sessions, and `NormMonitor` to check actions against the stored constitution:

```python
from normsync import NormStore, NormMonitor, NormRevision, WorldNorm, AgentAction, print_violations
import time

# Persist norms to SQLite (single file, shareable between agents)
store = NormStore(".normsync/norms.db")
norm = WorldNorm(
    name="no-attack-in-safe-zone",
    description="Attacking is prohibited in safe zones",
    condition="safe_zone",
    prohibited="attack",
)
store.save_norm(norm)
store.save_revision(NormRevision(norm_id=norm.id, revision_type="add", timestamp=time.time()))

# Load active norms into monitor and check actions
monitor = NormMonitor(store.get_norms(active_only=True))
action = AgentAction("hero", "attack", "safe_zone")
violations = monitor.check(action)
for v in violations:
    store.save_violation(v)

print_violations(violations)
# → Norm Violations table: hero | no-attack-in-safe-zone | ...

store.close()
```

**Track full norm history** with `NormVersionStore`:

```python
from normsync import NormStore, NormVersionStore, WorldNorm

store = NormStore(".normsync/norms.db")
version_store = NormVersionStore(store)

norm = WorldNorm(
    name="no-friendly-fire",
    description="Friendly fire is prohibited",
    condition="friendly",
    prohibited="attack",
)
store.save_norm(norm)
v1 = version_store.record_change(norm, changed_by="admin", reason="initial rule")

# Retrieve full version history
history = version_store.get_history("no-friendly-fire")
print(f"Version {history[0].version} by {history[0].changed_by}: {history[0].change_reason}")
store.close()
```

---

## CLI Reference

```bash
normsync [--db PATH] COMMAND [OPTIONS]
```

| Command | Description | Key options |
|---------|-------------|-------------|
| `add NAME DESC CONDITION PROHIBITED` | Add a norm to the constitution | `--scope`, `--priority`, `--db` |
| `check AGENT_ID ACTION [LOCATION]` | Check an action against active norms | `--target`, `--faction`, `--db` |
| `violations` | List all recorded violations | `--format {table,json,markdown}`, `--db` |
| `revisions` | List norm revision history | `--db` |
| `status` | Show constitution summary | `--db` |

**Examples:**

```bash
# Add a norm
normsync add no-attack "No attacking in safe zones" safe_zone attack

# Check an action
normsync check hero attack safe_zone

# Export violations as JSON
normsync violations --format json

# Check constitution status
normsync status
```

---

## GitHub Action

Add normsync norm checks to your CI pipeline:

```yaml
# .github/workflows/normsync.yml
name: normsync constitution check
on: [push, pull_request]

jobs:
  norm-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: sandeep-alluru/normsync@main
        with:
          db: .normsync/norms.db
          fail-on-violation: "true"
```

See [docs/github-action.md](docs/github-action.md) for full documentation.

---

## vs. Alternatives

| | normsync | OpenAI moderation | Constitutional AI | LangChain guardrails | Guardrails AI |
|---|---|---|---|---|---|
| **Norm-as-code** | Yes — version-controlled, content-addressed | No | No | No | No |
| **Runtime repeal** | Yes — deactivate without redeploying | No | No | No | No |
| **Multi-agent** | Yes — shared SQLite constitution | No | No | Limited | No |
| **Offline / local** | Yes — single SQLite file | No (API call) | No (training-time) | Partial | Partial |
| **CI exit code** | Yes — `normsync status --db` | No | No | No | No |
| **Primary purpose** | Agent norm enforcement | Content moderation | Model alignment | LLM output validation | Output validation |
| **Open source** | MIT | Closed | Closed | MIT | Apache 2.0 |

normsync is not a content moderation system. It is specifically designed to answer: *"Given these world norms, did this agent action violate any of them?"*

---

## Claude / MCP integration

normsync ships a Model Context Protocol server that lets Claude and other MCP-compatible agents define and check norms directly:

```bash
# Start the MCP server
python -m normsync.mcp_server

# In your Claude Code project's .claude/settings.json:
{
  "mcpServers": {
    "normsync": {
      "command": "python",
      "args": ["-m", "normsync.mcp_server"]
    }
  }
}
```

Once connected, Claude can call `normsync/add_norm`, `normsync/check_action`, and `normsync/list_violations` as tools. See [docs/mcp.md](docs/mcp.md) for the full tool schema.

---

## OpenAI integration

normsync exposes a FastAPI REST server compatible with OpenAI's function-calling format. The tool definitions are in [`tools/openai-tools.json`](tools/openai-tools.json) and the full API spec is in [`openapi.yaml`](openapi.yaml).

```bash
# Install with REST API dependencies
pip install 'normsync[api]'

# Start the REST server
uvicorn normsync.api:app --reload

# Pass to Codex CLI or any OpenAI-compatible agent
codex --tools tools/openai-tools.json "Check which agent actions violated the world constitution"
```

Endpoints: `GET /health`, `POST /norm`, `GET /norms`, `POST /check`, `GET /violations`. See [docs/openai.md](docs/openai.md) for details.

---

## Repository structure

```
normsync/
├── src/
│   └── normsync/
│       ├── norm.py           # WorldNorm, AgentAction, NormViolation, NormRevision dataclasses
│       ├── monitor.py        # NormMonitor — token-based norm checking
│       ├── store.py          # NormStore — SQLite persistence
│       ├── report.py         # print_violations(), to_json(), to_markdown()
│       ├── cli.py            # Click CLI (add, check, violations, revisions, status)
│       ├── api.py            # FastAPI REST server
│       └── mcp_server.py     # MCP server
├── tests/
│   ├── test_norm.py          # WorldNorm, AgentAction, NormViolation, NormRevision tests
│   ├── test_monitor.py       # NormMonitor unit tests
│   ├── test_store.py         # NormStore SQLite tests
│   ├── test_report.py        # Report formatter tests
│   ├── test_cli_runner.py    # CLI integration tests
│   └── test_api.py           # FastAPI endpoint tests
├── examples/
│   └── demo.py               # Standalone demo script
├── docs/                     # MkDocs documentation
├── tools/
│   └── openai-tools.json     # OpenAI function-calling tool definitions
├── assets/
│   ├── hero.png              # README hero image
│   └── logo.png              # Project logo
├── action.yml                # GitHub Action
├── openapi.yaml              # OpenAPI 3.1 spec
├── pyproject.toml            # Package metadata + dependencies
└── CONTRIBUTING.md           # Contribution guide
```

---

## GitHub Topics

Suggested topics for discoverability:

`ai-agents` `governance` `norms` `ai-alignment` `sqlite` `mcp` `llmops` `multi-agent` `simulation` `norm-enforcement` `world-constitution` `python`

---

## Smithery

normsync is available as an MCP server on [Smithery](https://smithery.ai). Search for `normsync` to install it directly into your Claude Desktop or other MCP-compatible client.

---

## Case Studies

See how teams are using normsync in production:

- [Real-Time Behavioral Governance for a 12-Agent AI Fleet](docs/case-studies/enterprise-ai-governance.md) — Apex Capital achieves 100% norm violation surfacing and a regulatorily defensible audit trail
- [Instant Norm Propagation for 200 Autonomous NPC Agents](docs/case-studies/game-faction-governance.md) — Horizon Games reduces faction norm update propagation from 20 minutes to <100ms

[![Star History Chart](https://api.star-history.com/svg?repos=sandeep-alluru/normsync&type=Date)](https://star-history.com/#sandeep-alluru/normsync&Date)

---

## Stay Updated

Subscribe to [**The Silence Layer**](https://newsletter.salluru.dev) — weekly dispatches on production AI infrastructure, new releases, and the failure modes that production AI systems don't surface until it's too late.


<!-- mcp-name: io.github.sandeep-alluru/normsync -->
