Metadata-Version: 2.4
Name: collective-intelligence-overlay
Version: 0.3.1
Summary: Evidence sharing and local admission for reusable agent capabilities
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pydantic>=2.13.5,<3
Requires-Dist: httpx>=0.28.1,<1
Requires-Dist: sqlalchemy>=2.1.1,<3
Requires-Dist: alembic>=1.20,<2
Requires-Dist: pg8000>=1.31,<2
Requires-Dist: securesystemslib[crypto]>=1.5.1,<2
Requires-Dist: pyjwt[crypto]>=2.12,<3
Requires-Dist: jsonschema>=4.26,<5
Requires-Dist: agent-framework-core>=1.19,<1.20 ; extra == 'agents'
Requires-Dist: a2a-sdk[http-server]>=1.1.5,<1.2 ; extra == 'agents'
Requires-Dist: mcp>=2.2,<2.3 ; extra == 'agents'
Requires-Dist: uvicorn>=0.41,<1 ; extra == 'agents'
Requires-Dist: httpx2>=2,<3 ; extra == 'agents'
Requires-Dist: agent-framework-openai>=1.14.4,<1.15 ; extra == 'model'
Requires-Python: >=3.12
Project-URL: Repository, https://github.com/kadubon/collective-intelligence-overlay
Provides-Extra: agents
Provides-Extra: model
Description-Content-Type: text/markdown

# Collective Intelligence Overlay

**Evidence is shared; admission is local.**

A Python overlay for teams that want agents to exchange reusable tools and procedures
without treating every generated result as verified. Each participant keeps its own
keys, database, acceptance policy and budget. A receiver can inspect a candidate,
request more checking, reject it, or reuse it under a specific contract.

The package connects Microsoft Agent Framework (MAF), A2A and MCP. It is not an
agent runtime or a central manager. Existing SDKs run tools and compose workflows;
the overlay records evidence, qualifies reuse and stops known-invalid dependencies.

[日本語](README.ja.md) · [Tutorial](docs/quickstart.md) · [Architecture](docs/architecture.md)

Version 0.2.1 returns execution allowance after a refusal or
cancellation only when the database proves no dispatch and fences further dispatch.
Inspection costs remain recorded; uncertain effects and old reservations stay held.
See [upgrade/recovery](docs/deployment.md) and [release state](docs/releasing.md).

Version **0.3.0** adds bounded owner goals, signed opportunities,
peer proposals and local work selection. The host registers the intended use,
installed builders and an independently qualified checker; observations then guide
finite formation, connection or verification work through the existing Executor.
Insufficient evidence, unavailable checkers, allowance shortage and uncertain
execution remain explicit stopping conditions. The tested release is available on
[PyPI](https://pypi.org/project/collective-intelligence-overlay/0.3.0/). See the [API](docs/api.md),
[external registration example](examples/adaptive_documents.py) and
[implementation and validation](docs/implementation-status.md).

## What works

The **0.3.1 candidate is not published**. It fixes four operational paths: bounded
exact-owner revocation for large histories; per-alternative rejection in proposal
collection/selection; explicit owner reobservation of expired opportunities; and
distinct logical A2A calls with saved retry/query IDs through Registry/Executor/MAF.
See the [API examples](docs/api.md) for revoke, rejection categories, `reobserve`
and `call_id`/`call_scope`, and [current results](docs/validation.md) for before/after
tests. The four source fixes have separate commits; the mandatory multi-Python/OS,
installed-artifact and publication gates remain pending. Mixed installed
3.12.14/3.14.7 peers passed both directions; Windows 3.13.15 full source passed
258 tests with zero failures/errors/skips.

Candidate metadata requires **Python >=3.12**, with no upper bound. The release
matrix requires current stable CPython 3.12.14/3.13.15/3.14.7 on Linux
and Windows; metadata does not mean all future interpreters are tested. Exact
runtime/profile results belong in [compatibility](docs/compatibility.md).
`.python-version` pins minimum-version development, not users' Python upper bound.
Select another interpreter explicitly with `uv sync --python 3.14.7 --all-extras --frozen`
and `uv run --python 3.14.7 ...`.

To upgrade from 0.3.0, stop old writers, back up and apply migrations 0013/0014.
Keep signed records, old remote IDs and UNKNOWN reservations; an empty new call
mapping never proves non-execution. [Offline upgrade/recovery](docs/deployment.md)
describes reconciliation and restart. This patch does not change the retained
negative pilot results or prove faster collective capability formation.

- Signed, versioned capability and evidence records, including PASS / FAIL / UNKNOWN.
- Receiver-specific OPA decisions: ACCEPT / REQUALIFY / REJECT / UNKNOWN.
- PostgreSQL persistence, duplicate/conflict detection, budgets and fenced result commits.
- Real A2A HTTP exchange, MAF function middleware/workflow composition and MCP HTTP calls.
- A three-process demo: register CSV tools, independently check their outputs and
  imported A2A bindings, reuse an HTML report workflow, then revoke its dependency.
- Typed costs and an explicitly limited deterministic comparison.

Version 0.2.0 adds typed local/MCP/A2A bindings,
durable invocations, paged synchronization/history and observed formation receipts.
An [external document application](examples/document_application.py) demonstrates
three peers building and checking C3, using it to construct C4, restarting and
stopping both descendants after withdrawal. See the [tutorial](docs/quickstart.md)
and [current validation scope](docs/implementation-status.md).

A signature establishes origin, not truth. Sample checks do not prove correctness on
all future data. Distinct local identities are not independent organizations or
statistically independent evidence. This software does not prove intelligence growth.

## Run from source

Python >=3.12, [uv](https://docs.astral.sh/uv/), PostgreSQL 16 and the OPA binary are
required for the reference path. No model API key is needed. There is no broker,
vector database, mandatory cloud service or always-running OPA server.

```sh
git clone https://github.com/kadubon/collective-intelligence-overlay.git
cd collective-intelligence-overlay
uv sync --all-extras --frozen
uv run python scripts/fetch_opa.py
```

Start a **dedicated development** PostgreSQL instance. The setup account must be able
to create roles and databases. See the [tutorial](docs/quickstart.md) for Docker,
Linux and PowerShell commands. Then:

```sh
export CIO_TEST_DATABASE_URL='postgresql+pg8000://postgres:development-only@127.0.0.1:5432/postgres'
export CIO_OPA="$PWD/.local/bin/opa"
uv run collective-intelligence-overlay demo --directory .local/demo
```

Expected fields: `processes: 3`, `admission: ACCEPT`, report total `117.00`,
`changed_environment: REQUALIFY`, `after_dependency_revocation: REJECT`.
Timings vary. The command preserves owner-local artifacts and databases and stops
its child processes. Use a new output directory for another run.

For the isolated fixed-versus-adaptive document comparison, use the
same service configuration and a fresh directory:

```sh
uv run python examples/evaluate_documents.py --directory .local/document-comparison --opa "$CIO_OPA" --seed 0
```

In PowerShell, pass `--opa "$env:CIO_OPA"`. This runs six separate three-peer arms
with no paid model calls. Normal and input-connection conditions passed three
held-out business tasks per arm in the recorded pilot; checking-constrained arms
stopped before those tasks. Adaptation showed no outcome or allowance advantage
and had higher elapsed observations in that single run. [Raw results and limits](docs/evaluation.md)
distinguish working integration from demonstrated benefit.

[Version 0.3.0 is published on PyPI](https://pypi.org/project/collective-intelligence-overlay/0.3.0/).
To install into an activated Python 3.12 environment:

```sh
uv pip install 'collective-intelligence-overlay[agents]==0.3.0'
collective-intelligence-overlay --version
```

PostgreSQL and OPA are still required for the reference demo. Actual publication
status, hashes and clean-install verification are recorded in [releasing](docs/releasing.md).
For 0.1.0 upgrades, follow [migration and recovery](docs/deployment.md).

## Add to an existing agent

Importing the core never opens a database or runs a migration. The host supplies
an `Overlay`, explicitly installed `Registry` bindings and a persistent `Executor`:

```python
registry.register_local(binding, operation, assess)
invocation = await executor.invoke(
    "caller-stable-operation-id", binding.id, binding.digest, arguments, context
)
```

Here the host supplies the pinned binding, installed function, input assessment,
execution context and executor connected to that registry. Publish the corresponding
candidate and obtain independent evidence before ordinary reuse.
The executor checks the binding and actual inputs at execution, reserves the owner's
budget and retains the result under the caller's stable ID. Completion is not an
independent PASS. A previous ACCEPT is not a permanent permission. The lower-level
`Overlay.execute` callback API remains available for compatibility.
[Integration](docs/integrations.md) shows registration, MAF
middleware and the real, opt-in model example. See [API and CLI](docs/api.md) for
configuration, exceptions, cancellation and the operator/agent boundary.

For example, a verifier's PASS for `csv-sum@1` in environment `reference=1` does not
admit it in `reference=2`. The receiver requests requalification. A valid in-scope
counterexample is retained alongside the PASS and takes precedence in the standard policy.

## Trust and operation

Peers authenticate with distinct pinned Ed25519 identities. Local Rego policy,
keys and budgets must be protected from the agent process. Evidence sharing is
disabled by default; the demonstration enables it for its configured peers.
The DB/host operator is trusted. A malicious infrastructure administrator is outside
this model. See [security](docs/security.md) and [deployment](docs/deployment.md).

```sh
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest
uv build
uv run twine check --strict dist/*
uv run python scripts/check_package.py
```

Integration/E2E tests require PostgreSQL and OPA; missing services are explicit skips,
not production validation. Paid model calls are off by default. Current checks and
unverified boundaries are in [validation](docs/validation.md). Windows and Linux are
the initial target platforms; the network reference deployment is Linux-oriented.

New code is Apache-2.0. See [LICENSE](LICENSE), [NOTICE](NOTICE),
[dependency compatibility/licensing](docs/compatibility.md),
[research mapping](docs/research-mapping.md), and [contributing](CONTRIBUTING.md).
