Metadata-Version: 2.4
Name: keppler
Version: 0.2.0
Summary: Human-gated knowledge exchange for agent fleets
Project-URL: Homepage, https://github.com/pisigmac/Keppler
Project-URL: Repository, https://github.com/pisigmac/Keppler.git
Project-URL: Issues, https://github.com/pisigmac/Keppler/issues
Keywords: agents,a2a,mcp,knowledge,federation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Provides-Extra: server
Requires-Dist: fastapi<1,>=0.115; extra == "server"
Requires-Dist: pydantic<3,>=2.10; extra == "server"
Requires-Dist: uvicorn[standard]<1,>=0.34; extra == "server"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: fastapi<1,>=0.115; extra == "dev"
Requires-Dist: httpx<1,>=0.28; extra == "dev"
Requires-Dist: pydantic<3,>=2.10; extra == "dev"
Requires-Dist: pytest<9,>=8.3; extra == "dev"
Requires-Dist: twine<7,>=6.1; extra == "dev"
Requires-Dist: uvicorn[standard]<1,>=0.34; extra == "dev"

# Keppler

Keppler is a human-gated learning layer for agent fleets. Agents submit
patterns with evidence, a debate engine challenges and evaluates each proposal,
and a reviewer decides what enters the immutable knowledge history.

The current local reference implementation includes the core learning loop and
the organization/federation protocol foundation:

1. register an agent;
2. propose a pattern with evidence;
3. run a deterministic challenge and evaluation;
4. approve or reject the proposal in the review console; and
5. expose approved knowledge to another agent;
6. isolate resources by organization namespace;
7. federate approved knowledge with explicit receiver consent;
8. expose approved patterns as read-only MCP tools; and
9. bridge pattern proposals to the A2A 1.0 REST task lifecycle.

The original roadmap briefs are preserved as product inputs. The implemented
scope and explicit non-goals live in [docs/PRODUCT_SCOPE.md](docs/PRODUCT_SCOPE.md).

## Quick start

### Install from PyPI

The client and observer use only the Python standard library:

```bash
python -m pip install keppler
```

Install the API server dependencies when hosting Keppler:

```bash
python -m pip install 'keppler[server]'
keppler
```

### API development

Keppler targets Python 3.12.

```bash
python3.12 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/uvicorn keppler.api:app --reload --port 8000
```

The API documentation is then available at `http://localhost:8000/docs`.

### Review console

Keppler targets Node.js 22.12+ and pnpm.

```bash
cd frontend
pnpm install
pnpm dev
```

Open `http://localhost:5173`. The console expects the API at
`http://localhost:8000` unless `VITE_API_URL` is set.

### Tests

```bash
.venv/bin/pytest backend/tests
cd frontend && pnpm build
```

## API walkthrough

Register an agent:

```bash
curl -X POST http://localhost:8000/v1/agents \
  -H 'content-type: application/json' \
  -d '{"name":"agent-a","capabilities":["postgres","api-design"]}'
```

Submit a pattern using the returned agent ID:

```bash
curl -X POST http://localhost:8000/v1/proposals \
  -H 'content-type: application/json' \
  -d '{
    "agent_id":"<agent-id>",
    "title":"Bound database concurrency",
    "context":"A service opens many concurrent PostgreSQL connections.",
    "pattern":"Use a bounded connection pool and measure queue wait time.",
    "evidence":[
      "Load test reduced open connections from 120 to 20.",
      "p95 request latency fell from 420ms to 180ms."
    ]
  }'
```

Proposals with sufficient evidence enter `pending_review`; the review console
can approve them into the knowledge history.

Organization-aware requests are scoped with `X-Keppler-Org`. Omitting it preserves legacy
behavior by selecting the built-in local organization. This header is context,
not authentication; see [docs/MULTI-TENANCY.md](docs/MULTI-TENANCY.md) before any
production deployment.

## Product APIs

- `POST /v1/kep/messages` — KEP 0.1/1.0 pattern envelopes
- `GET/POST /v1/organizations` — organization namespaces
- `GET /v1/skills` and `POST /mcp` — MCP skill discovery and invocation
- `GET/POST /v1/federation` — receiver-consented federation workflow
- `GET /v1/sync?after=<sequence>` — organization-scoped delta feed
- `/.well-known/agent-card.json`, `/message:send`, `/tasks/{id}` — A2A bridge
