convergentAI 1.0.0__tar.gz

convergentai-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AreteDriver
+
+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.

convergentai-1.0.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: convergentAI
+Version: 1.0.0
+Summary: Multi-agent coherence and coordination for AI systems
+Author: AreteDriver
+License: MIT
+Project-URL: Homepage, https://github.com/AreteDriver/convergent
+Project-URL: Repository, https://github.com/AreteDriver/convergent
+Project-URL: Issues, https://github.com/AreteDriver/convergent/issues
+Keywords: multi-agent,ai,orchestration,convergence,intent-graph
+Classifier: Development Status :: 5 - Production/Stable
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.39.0; extra == "llm"
+Provides-Extra: rust
+Requires-Dist: maturin<2.0,>=1.0; extra == "rust"
+Dynamic: license-file
+
+# Convergent
+
+Coordination library for multi-agent AI systems. Agents share an intent graph, detect overlaps before building, and converge on compatible outputs — eliminating rework cycles from parallel code generation.
+
+[![CI](https://github.com/AreteDriver/convergent/actions/workflows/ci.yml/badge.svg)](https://github.com/AreteDriver/convergent/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://img.shields.io/badge/tests-800+-brightgreen.svg)]()
+[![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen.svg)]()
+
+## Why This Exists
+
+- **Problem:** Parallel AI agents generating code independently produce incompatible outputs. Agent A builds `User` with `int` IDs while Agent B uses `UUID`. Code fails to merge. 2-3 rework cycles before anything integrates.
+- **Audience:** Multi-agent orchestration frameworks, distributed systems with autonomous agents, anyone running parallel AI code generation.
+- **Outcome:** Agents publish what they're building to a shared intent graph. Before starting work, they check for overlaps and adopt existing decisions. Compatible output on first try. Zero rework.
+
+## What It Does
+
+- **Intent graph** — Shared, append-only graph of architectural decisions. Agents publish intents (what they build, what they need) and query for overlaps
+- **Structural matching** — Detect when two agents plan to build the same interface based on name, kind, and tag similarity
+- **Stability scoring** — Evidence-weighted confidence (test passes, code commits, downstream consumers) determines which intent wins conflicts
+- **Constraint enforcement** — Hard requirements that must hold (type checks pass, no circular deps) validated by subprocess gates
+- **Triumvirate voting** — Phi-weighted consensus engine with configurable quorum (ANY, MAJORITY, UNANIMOUS)
+- **Stigmergy** — Trail markers that agents leave for future agents, with exponential decay (inspired by ant pheromone trails)
+- **Flocking** — Emergent group behavior from local rules: alignment (adopt patterns), cohesion (detect drift), separation (avoid file conflicts)
+- **Zero dependencies** — Pure Python, stdlib only. Optional Rust acceleration via PyO3
+
+## Quickstart
+
+### Prerequisites
+
+- Python 3.10+
+
+### Install
+
+```bash
+pip install convergent
+# or from source:
+git clone https://github.com/AreteDriver/convergent.git
+cd convergent
+pip install -e .
+```
+
+### Run
+
+```python
+from convergent import IntentResolver, PythonGraphBackend, Intent, InterfaceSpec
+
+resolver = IntentResolver(backend=PythonGraphBackend())
+
+# Agent A publishes what it's building
+resolver.publish(Intent(
+    intent_id="auth-service",
+    agent_id="agent-a",
+    description="JWT authentication service",
+    interfaces=[
+        InterfaceSpec(name="User", kind="class", tags=["auth", "model"]),
+    ],
+))
+
+# Agent B checks for overlapping work before starting
+overlaps = resolver.find_overlapping(Intent(
+    intent_id="user-module",
+    agent_id="agent-b",
+    description="User management",
+    interfaces=[
+        InterfaceSpec(name="User", kind="class", tags=["auth", "model"]),
+    ],
+))
+# → overlaps shows agent-a already owns the User class
+# → agent-b adopts agent-a's schema instead of building its own
+```
+
+## Usage Examples
+
+### Example 1: Persistent intent graph with SQLite
+
+```python
+from convergent import IntentResolver, SQLiteBackend
+
+# WAL mode, concurrent reads, persistent across restarts
+resolver = IntentResolver(backend=SQLiteBackend("./intents.db"))
+resolver.publish(intent)
+
+# Inspect from CLI
+# python -m convergent inspect ./intents.db --format table
+```
+
+### Example 2: Consensus voting
+
+```python
+from convergent import GorgonBridge, CoordinationConfig
+
+bridge = GorgonBridge(CoordinationConfig(db_path="./coordination.db"))
+
+# Request a vote
+request_id = bridge.request_consensus(
+    task_id="pr-42",
+    question="Should we merge this PR?",
+    context="All tests pass, adds new auth endpoint",
+)
+
+# Agents vote (phi-weighted by historical trust)
+bridge.submit_agent_vote(
+    request_id, "agent-1", "reviewer", "claude:sonnet",
+    "approve", 0.9, "LGTM"
+)
+
+decision = bridge.evaluate(request_id)
+# → DecisionOutcome.APPROVED
+```
+
+### Example 3: Enrich agent prompts with coordination context
+
+```python
+context = bridge.enrich_prompt(
+    agent_id="agent-1",
+    task_description="implement auth",
+    file_paths=["src/auth.py"],
+)
+# → Returns stigmergy markers + flocking constraints + phi score context
+# → Inject into agent's system prompt for coordination-aware generation
+```
+
+## Architecture
+
+```text
+Gorgon (orchestrator)
+    │
+    ▼
+┌── Convergent ───────────────────────────────────────┐
+│                                                      │
+│  Coordination Protocol (Phase 3)                     │
+│  ┌────────────┐  ┌───────────┐  ┌─────────┐        │
+│  │ Triumvirate │  │ Stigmergy │  │Flocking │        │
+│  │ (voting)    │  │ (trails)  │  │ (swarm) │        │
+│  └──────┬──────┘  └─────┬─────┘  └────┬────┘        │
+│         └───────┬───────┴─────────────┘              │
+│                 ▼                                     │
+│  Intent Graph + Intelligence (Phase 1-2)             │
+│  ┌──────────────────────────────────────────┐        │
+│  │ Resolver │ Contracts │ Governor │ Gates  │        │
+│  └──────────────────────────────────────────┘        │
+│                 ▼                                     │
+│  ┌──────────────────────────────────────────┐        │
+│  │ Python (memory) │ SQLite │ Rust (opt)    │        │
+│  └──────────────────────────────────────────┘        │
+└──────────────────────────────────────────────────────┘
+```
+
+**Key components:**
+
+| Component | Purpose |
+|-----------|---------|
+| `IntentResolver` | Query the intent graph, detect overlaps, resolve conflicts |
+| `MergeGovernor` | Three-layer decision authority: constraints → intents → economics |
+| `Triumvirate` | Phi-weighted voting with configurable quorum levels |
+| `StigmergyField` | Trail markers with exponential decay for indirect agent communication |
+| `FlockingCoordinator` | Alignment, cohesion, separation rules for emergent coordination |
+| `GorgonBridge` | Single entry point for orchestrator integration |
+
+## Testing
+
+```bash
+# Python-only (no Rust needed)
+PYTHONPATH=python pytest tests/ -v
+
+# With optional Rust acceleration
+maturin develop --release && pytest tests/ -v
+
+# Lint
+ruff check python/ tests/ && ruff format --check python/ tests/
+```
+
+800+ tests, 99% coverage, CI green.
+
+## Roadmap
+
+- **v1.0.0** (current): Stable API contract, published to PyPI, PEP 561 py.typed
+- **v0.6.0**: Pluggable signal bus (SQLite cross-process + filesystem), decision history query API
+- **v0.5.0**: Coordination protocol (triumvirate voting, stigmergy, flocking, signal bus)
+- **v0.4.0**: CLI inspector, async backend, Rust backend parity
+
+## License
+
+[MIT](LICENSE)

convergentai-1.0.0/README.md

@@ -0,0 +1,186 @@
+# Convergent
+
+Coordination library for multi-agent AI systems. Agents share an intent graph, detect overlaps before building, and converge on compatible outputs — eliminating rework cycles from parallel code generation.
+
+[![CI](https://github.com/AreteDriver/convergent/actions/workflows/ci.yml/badge.svg)](https://github.com/AreteDriver/convergent/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://img.shields.io/badge/tests-800+-brightgreen.svg)]()
+[![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen.svg)]()
+
+## Why This Exists
+
+- **Problem:** Parallel AI agents generating code independently produce incompatible outputs. Agent A builds `User` with `int` IDs while Agent B uses `UUID`. Code fails to merge. 2-3 rework cycles before anything integrates.
+- **Audience:** Multi-agent orchestration frameworks, distributed systems with autonomous agents, anyone running parallel AI code generation.
+- **Outcome:** Agents publish what they're building to a shared intent graph. Before starting work, they check for overlaps and adopt existing decisions. Compatible output on first try. Zero rework.
+
+## What It Does
+
+- **Intent graph** — Shared, append-only graph of architectural decisions. Agents publish intents (what they build, what they need) and query for overlaps
+- **Structural matching** — Detect when two agents plan to build the same interface based on name, kind, and tag similarity
+- **Stability scoring** — Evidence-weighted confidence (test passes, code commits, downstream consumers) determines which intent wins conflicts
+- **Constraint enforcement** — Hard requirements that must hold (type checks pass, no circular deps) validated by subprocess gates
+- **Triumvirate voting** — Phi-weighted consensus engine with configurable quorum (ANY, MAJORITY, UNANIMOUS)
+- **Stigmergy** — Trail markers that agents leave for future agents, with exponential decay (inspired by ant pheromone trails)
+- **Flocking** — Emergent group behavior from local rules: alignment (adopt patterns), cohesion (detect drift), separation (avoid file conflicts)
+- **Zero dependencies** — Pure Python, stdlib only. Optional Rust acceleration via PyO3
+
+## Quickstart
+
+### Prerequisites
+
+- Python 3.10+
+
+### Install
+
+```bash
+pip install convergent
+# or from source:
+git clone https://github.com/AreteDriver/convergent.git
+cd convergent
+pip install -e .
+```
+
+### Run
+
+```python
+from convergent import IntentResolver, PythonGraphBackend, Intent, InterfaceSpec
+
+resolver = IntentResolver(backend=PythonGraphBackend())
+
+# Agent A publishes what it's building
+resolver.publish(Intent(
+    intent_id="auth-service",
+    agent_id="agent-a",
+    description="JWT authentication service",
+    interfaces=[
+        InterfaceSpec(name="User", kind="class", tags=["auth", "model"]),
+    ],
+))
+
+# Agent B checks for overlapping work before starting
+overlaps = resolver.find_overlapping(Intent(
+    intent_id="user-module",
+    agent_id="agent-b",
+    description="User management",
+    interfaces=[
+        InterfaceSpec(name="User", kind="class", tags=["auth", "model"]),
+    ],
+))
+# → overlaps shows agent-a already owns the User class
+# → agent-b adopts agent-a's schema instead of building its own
+```
+
+## Usage Examples
+
+### Example 1: Persistent intent graph with SQLite
+
+```python
+from convergent import IntentResolver, SQLiteBackend
+
+# WAL mode, concurrent reads, persistent across restarts
+resolver = IntentResolver(backend=SQLiteBackend("./intents.db"))
+resolver.publish(intent)
+
+# Inspect from CLI
+# python -m convergent inspect ./intents.db --format table
+```
+
+### Example 2: Consensus voting
+
+```python
+from convergent import GorgonBridge, CoordinationConfig
+
+bridge = GorgonBridge(CoordinationConfig(db_path="./coordination.db"))
+
+# Request a vote
+request_id = bridge.request_consensus(
+    task_id="pr-42",
+    question="Should we merge this PR?",
+    context="All tests pass, adds new auth endpoint",
+)
+
+# Agents vote (phi-weighted by historical trust)
+bridge.submit_agent_vote(
+    request_id, "agent-1", "reviewer", "claude:sonnet",
+    "approve", 0.9, "LGTM"
+)
+
+decision = bridge.evaluate(request_id)
+# → DecisionOutcome.APPROVED
+```
+
+### Example 3: Enrich agent prompts with coordination context
+
+```python
+context = bridge.enrich_prompt(
+    agent_id="agent-1",
+    task_description="implement auth",
+    file_paths=["src/auth.py"],
+)
+# → Returns stigmergy markers + flocking constraints + phi score context
+# → Inject into agent's system prompt for coordination-aware generation
+```
+
+## Architecture
+
+```text
+Gorgon (orchestrator)
+    │
+    ▼
+┌── Convergent ───────────────────────────────────────┐
+│                                                      │
+│  Coordination Protocol (Phase 3)                     │
+│  ┌────────────┐  ┌───────────┐  ┌─────────┐        │
+│  │ Triumvirate │  │ Stigmergy │  │Flocking │        │
+│  │ (voting)    │  │ (trails)  │  │ (swarm) │        │
+│  └──────┬──────┘  └─────┬─────┘  └────┬────┘        │
+│         └───────┬───────┴─────────────┘              │
+│                 ▼                                     │
+│  Intent Graph + Intelligence (Phase 1-2)             │
+│  ┌──────────────────────────────────────────┐        │
+│  │ Resolver │ Contracts │ Governor │ Gates  │        │
+│  └──────────────────────────────────────────┘        │
+│                 ▼                                     │
+│  ┌──────────────────────────────────────────┐        │
+│  │ Python (memory) │ SQLite │ Rust (opt)    │        │
+│  └──────────────────────────────────────────┘        │
+└──────────────────────────────────────────────────────┘
+```
+
+**Key components:**
+
+| Component | Purpose |
+|-----------|---------|
+| `IntentResolver` | Query the intent graph, detect overlaps, resolve conflicts |
+| `MergeGovernor` | Three-layer decision authority: constraints → intents → economics |
+| `Triumvirate` | Phi-weighted voting with configurable quorum levels |
+| `StigmergyField` | Trail markers with exponential decay for indirect agent communication |
+| `FlockingCoordinator` | Alignment, cohesion, separation rules for emergent coordination |
+| `GorgonBridge` | Single entry point for orchestrator integration |
+
+## Testing
+
+```bash
+# Python-only (no Rust needed)
+PYTHONPATH=python pytest tests/ -v
+
+# With optional Rust acceleration
+maturin develop --release && pytest tests/ -v
+
+# Lint
+ruff check python/ tests/ && ruff format --check python/ tests/
+```
+
+800+ tests, 99% coverage, CI green.
+
+## Roadmap
+
+- **v1.0.0** (current): Stable API contract, published to PyPI, PEP 561 py.typed
+- **v0.6.0**: Pluggable signal bus (SQLite cross-process + filesystem), decision history query API
+- **v0.5.0**: Coordination protocol (triumvirate voting, stigmergy, flocking, signal bus)
+- **v0.4.0**: CLI inspector, async backend, Rust backend parity
+
+## License
+
+[MIT](LICENSE)

convergentai-1.0.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "convergentAI"
+version = "1.0.0"
+description = "Multi-agent coherence and coordination for AI systems"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "AreteDriver" }
+]
+keywords = ["multi-agent", "ai", "orchestration", "convergence", "intent-graph"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Rust",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "pytest-benchmark>=4.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0",
+]
+llm = [
+    "anthropic>=0.39.0",
+]
+rust = [
+    "maturin>=1.0,<2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/AreteDriver/convergent"
+Repository = "https://github.com/AreteDriver/convergent"
+Issues = "https://github.com/AreteDriver/convergent/issues"
+
+[tool.setuptools.packages.find]
+where = ["python"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "A", "SIM"]
+
+[tool.ruff.lint.per-file-ignores]
+"python/convergent/contract.py" = ["N818"]  # ContractViolation is the public API name
+
+[tool.coverage.run]
+omit = [
+    "python/convergent/semantic.py",
+    "python/convergent/demo.py",
+]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true