Metadata-Version: 2.4
Name: collective-intelligence-overlay
Version: 0.5.0
Summary: Evidence-preserving capability lifecycle and receiver-local admission
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-Dist: agent-framework-ollama==1.0.0b260813 ; extra == 'ollama'
Requires-Python: >=3.12
Project-URL: Repository, https://github.com/kadubon/collective-intelligence-overlay
Provides-Extra: agents
Provides-Extra: model
Provides-Extra: ollama
Description-Content-Type: text/markdown

# Collective Intelligence Overlay

Collective Intelligence Overlay is an evidence-preserving capability lifecycle layer.
It connects original records of a tool or procedure to its verification, receiver
decisions, uses, costs and unresolved checks. It does not certify functional novelty,
causal contribution or intelligence growth.

For example, before using another agent's CSV tool, inspect the exact tool version,
what a separate checker tested, who accepted or rejected it, and which costs or
effects remain unknown. Each participant retains its own policy, keys and budget:
**Evidence is shared; admission is local.**

[日本語](README.ja.md) · [Start here](docs/start.md) ·
[Tutorial](docs/lifecycle-tutorial.md) · [API reference](docs/lifecycle-reference.md)

## Install and services

The **0.5.0 candidate is not yet published**. Use its reviewed wheel; publication and
exact hashes will be recorded in [release status](docs/releasing.md). These examples
target 0.5.0. The published 0.4.4 record remains in the [archive](docs/research-archive.md).

Core record models and offline views need no running service or model. Owner database
inspection and explicit qualification use PostgreSQL and OPA. Optional `[agents]`
integrates Microsoft Agent Framework (MAF), A2A and MCP; `[model]` and `[ollama]`
are separate optional model integrations. Finding credentials does not enable inference.

## First run from the installed package

Run from a fresh directory outside the repository, with the reviewed pair in
`../candidate/dist`. On Linux/macOS:

```sh
uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install ../candidate/dist/collective_intelligence_overlay-0.5.0-py3-none-any.whl
collective-intelligence-overlay lifecycle inspect --fixture
```

On Windows PowerShell:

```powershell
uv venv .venv --python 3.12
. .venv/Scripts/Activate.ps1
uv pip install ../candidate/dist/collective_intelligence_overlay-0.5.0-py3-none-any.whl
collective-intelligence-overlay lifecycle inspect --fixture
```

The bundled input is **explicitly synthetic**. JSON retains PASS, different receiver
decisions, completed reuse, unavailable cost and withdrawal as separate observations.
It reports `current_admission: unassessed` and `execution_authority: not_granted`.
No database, network, model, tool or policy is invoked. Residual means a recorded
unresolved check, not an automatically assigned task or legal responsibility.

## Connect an existing tool

<a id="register-your-application"></a>

Follow the [model-free service tutorial](docs/lifecycle-tutorial.md): install `[agents]`,
register trusted local tools through the existing Registry/Executor, use independent
checks and receiver-local OPA decisions, then inspect actual reuse and withdrawal.
The tutorial uses a dedicated PostgreSQL service and OPA; it launches no model.
For a three-process peer deployment and your own application, continue with
[registration and network setup](docs/quickstart.md) and [integrations](docs/integrations.md).

## Five observations

<a id="what-it-provides"></a>

| Type | What it exposes |
|---|---|
| `CapabilityLifecycleView` | Exact candidate, evidence, historical decisions, use, costs and withdrawal |
| `ContributionObservation` | Copy, import, reuse, formation inputs and new candidate; no causal credit |
| `Residual` | Missing, unknown, stale or incompatible material with original references |
| `GrowthObservation` | Independent stock endpoints, period service observations and typed costs |
| `HandoffObservation` | Typed proposed/received/assessed material; no transport or execution grant |

The [SDK and CLI](docs/lifecycle-reference.md) use finite material or bounded owner pages.
`inspect_lifecycle`, `observe_contributions`, `observe_growth` and `build_handoff` are
read-only. Explicit `assess_stock` delegates to existing qualification and saves Decisions.
Core lifecycle imports no agent or transport SDK. Existing MAF/A2A/MCP adapters
retain execution responsibility; there is no new scheduler, event store or central manager.

## History, authority and data

<a id="operate-and-assess"></a>

Historical PASS, ACCEPT, a valid signature and a completed receipt are distinct from
current admission, execution permission and business quality. Execution still passes
the existing Executor gate. UNKNOWN, absent, FAIL, unperformed and expired material
remain distinct. Entry counts use declared record identities, not semantic ability counts.

The host, database operator and installed checker remain trusted. Read access is owner
restricted. References never fetch URLs or paths automatically. Explicit original export
preserves signed payload bytes; view JSON has its own digest. Keep private originals,
keys and logs protected. Pagination, expiry and deletion do not resolve uncertain effects.
See [concepts](docs/lifecycle-concepts.md), [security](SECURITY.md) and
[deployment/recovery](docs/deployment.md).

## Compatibility and verification

Python >=3.12; declared Linux, Windows, macOS Intel and Apple Silicon profiles remain
in the [runtime matrix](docs/validation.md). Candidate verification and pending native
and publication gates are tracked in [the implementation register](docs/lifecycle-050-implementation.md).
No DB migration or wire record change is introduced by the lifecycle layer.
[Migration](docs/migration-050.md) explains legacy missing bindings and clocks.

Source checks: `uv sync --all-extras --frozen`, `uv run ruff check .`, `uv run mypy`,
`uv run pytest`, `uv run python scripts/check_docs.py`, `uv build`.
Service skips are not evidence of a passing deployment. The repository is Apache-2.0;
dependency conditions are in [compatibility](docs/compatibility.md).

Historical negative and limited results remain in the [research archive](docs/research-archive.md).
CIO-specific accumulation benefit is unproven. No new model generation, research
comparison, benchmark or long soak is part of this feature release.
