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.

Quick start

Install from PyPI

The client and observer use only the Python standard library:

python -m pip install keppler

Install the API server dependencies when hosting Keppler:

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

API development

Keppler targets Python 3.12.

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.

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

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

API walkthrough

Register an agent:

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:

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 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