feat: Add CapiscIO.connect() for Let's Encrypt-style agent setup by beonde · Pull Request #26 · capiscio/capiscio-sdk-python

beonde · 2026-02-05T21:19:14Z

Summary

Implements a "Let's Encrypt" style one-liner setup for Python SDK. CapiscIO.connect() handles everything automatically: key generation, DID derivation, server registration, and badge setup.

Usage

from capiscio_sdk import CapiscIO

# One line - handles everything automatically
agent = CapiscIO.connect(api_key="sk_live_...")

print(agent.did)    # did:key:z6Mk...
print(agent.badge)  # Your trust badge

# Emit events for observability
agent.emit("task_started", {"task_id": "123"})

Or from environment variables:

# Set CAPISCIO_API_KEY in your environment
agent = CapiscIO.from_env()

Changes

New Modules

connect.py (~395 lines)

CapiscIO.connect() - Main entry point
CapiscIO.from_env() - Environment variable configuration
AgentIdentity dataclass with methods:
- emit() - Emit events to registry
- get_badge() - Get current badge (auto-renewed)
- status() - Get agent status dict

events.py (~319 lines)

EventEmitter class with batching for efficient event emission
Standard event types: agent_started, task_started, task_completed, etc.

Proto Updates

Regenerated all proto bindings with Init RPC support
Updated import paths for consistency

Documentation

Updated quickstart.md with CapiscIO.connect() as Step 1

Two Setup Paths

Path	When to Use	Code
Quick Start	Getting started, single agent	`CapiscIO.connect(api_key="...")`
UI-First	Teams, multiple agents	`CapiscIO.connect(api_key="...", agent_id="agt_123")`

Dependencies

Added base58>=2.1.0 to dev dependencies for DID verification tests.

Related PRs

capiscio-core#32: CLI capiscio init command
capiscio-docs: Documentation updates (coming)

- Add connect.py with CapiscIO.connect() and CapiscIO.from_env() - Add events.py with EventEmitter for agent observability - AgentIdentity dataclass with emit(), get_badge(), status() methods - Auto-discover agent, generate keys via gRPC, register DID - Update quickstart docs with new one-liner setup - Regenerate proto bindings with Init RPC support

github-actions · 2026-02-05T21:19:56Z

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

Copilot

Pull request overview

This PR implements a "Let's Encrypt" style one-liner agent setup for the CapiscIO Python SDK, significantly simplifying the onboarding process. The new CapiscIO.connect() method automates key generation, DID derivation, server registration, and badge setup. Additionally, it introduces event emission capabilities for observability.

Changes:

Added CapiscIO.connect() and CapiscIO.from_env() for simplified agent identity setup
Added EventEmitter class with batching for efficient event emission to the registry
Regenerated proto bindings to support the new Init RPC in SimpleGuardService

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 26 comments.

Show a summary per file

File	Description
`capiscio_sdk/connect.py`	New module implementing "Let's Encrypt" style agent setup with `CapiscIO.connect()` and `AgentIdentity` dataclass
`capiscio_sdk/events.py`	New module providing event emission to registry with batching and standard event types
`capiscio_sdk/_rpc/client.py`	Added `init()` method to SimpleGuardClient for one-call identity initialization
`capiscio_sdk/_rpc/gen/capiscio/v1/*.py`	Regenerated proto bindings with Init RPC support and updated protobuf version (6.33.4→6.33.5)
`capiscio_sdk/__init__.py`	Exported new `CapiscIO`, `connect`, `from_env`, `AgentIdentity`, and `EventEmitter` APIs
`docs/getting-started/quickstart.md`	Updated quickstart with `CapiscIO.connect()` as Step 1, showing one-line setup
`pyproject.toml`	Added `base58>=2.1.0` dev dependency for DID verification tests

capiscio_sdk/connect.py

capiscio_sdk/_rpc/gen/capiscio/v1/trust_pb2_grpc.py

capiscio_sdk/_rpc/gen/capiscio/v1/trust_pb2.py

capiscio_sdk/_rpc/gen/capiscio/v1/badge_pb2_grpc.py

capiscio_sdk/connect.py

capiscio_sdk/_rpc/gen/capiscio/v1/revocation_pb2.py

capiscio_sdk/_rpc/gen/capiscio/v1/scoring_pb2.py

capiscio_sdk/_rpc/gen/capiscio/v1/simpleguard_pb2.py

capiscio_sdk/_rpc/gen/capiscio/v1/trust_pb2.py

github-actions · 2026-02-05T21:49:09Z

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

- Fix BadgeKeeper.get_badge() -> get_current_badge() (2 places) - Fix proto import paths: from capiscio.v1 -> from capiscio_sdk._rpc.gen.capiscio.v1 - Remove unused json imports from connect.py and events.py

github-actions · 2026-02-05T21:55:34Z

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

github-actions · 2026-02-05T21:57:15Z

✅ All checks passed! Ready for review.

codecov · 2026-02-05T21:57:52Z

Codecov Report

❌ Patch coverage is 92.14286% with 22 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
capiscio_sdk/connect.py	87.64%	21 Missing ⚠️
capiscio_sdk/events.py	99.07%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

github-actions · 2026-02-05T21:58:04Z

✅ Integration tests passed! Server validation, BadgeKeeper, and gRPC tests all working.

Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 13 comments.

capiscio_sdk/connect.py

pyproject.toml

capiscio_sdk/connect.py

capiscio_sdk/events.py

capiscio_sdk/connect.py

capiscio_sdk/events.py

capiscio_sdk/connect.py

- Add 32 tests for connect.py (AgentIdentity, CapiscIO.connect, from_env, _Connector) - Add 28 tests for events.py (EventEmitter, global functions) - Improve patch coverage for new Let's Encrypt-style setup feature

github-actions · 2026-02-05T22:16:01Z

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

github-actions · 2026-02-05T22:18:20Z

✅ Integration tests passed! Server validation, BadgeKeeper, and gRPC tests all working.

github-actions · 2026-02-05T22:19:11Z

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

github-actions · 2026-02-05T22:20:14Z

✅ All checks passed! Ready for review.

github-actions · 2026-02-05T22:21:01Z

✅ Integration tests passed! Server validation, BadgeKeeper, and gRPC tests all working.

- Add tests for full connect() flow with/without badge - Add tests for _ensure_agent error paths - Add tests for _create_agent edge cases - Add tests for _init_identity with RPC and existing files - Add tests for _setup_badge success and failure - Coverage improved from 63% to 99% for connect.py

github-actions · 2026-02-05T22:25:01Z

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 16 comments.

capiscio_sdk/connect.py

capiscio_sdk/events.py

capiscio_sdk/connect.py

tests/unit/test_events.py

tests/unit/test_connect.py

tests/unit/test_events.py

github-actions · 2026-02-05T22:27:38Z

✅ Integration tests passed! Server validation, BadgeKeeper, and gRPC tests all working.

…leanup - connect.py: Add AgentIdentity.close() for resource cleanup - connect.py: Add finally block in connect() to close httpx/gRPC clients - connect.py: Sanitize error messages to not expose internal RPC details - connect.py: Fix badge_expires_at attribute access with hasattr - events.py: Add threading.Lock for thread-safe batch operations - events.py: Wrap emit() and flush() batch access with _batch_lock - test_connect.py: Remove unused PropertyMock import - test_events.py: Remove unused imports (time, datetime, timezone, _global_emitter)

github-actions · 2026-02-05T22:33:39Z

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

github-actions · 2026-02-05T22:36:06Z

✅ Integration tests passed! Server validation, BadgeKeeper, and gRPC tests all working.

Directly set _rpc_client on connector instead of patching, avoids naming conflict between capiscio_sdk.connect module and CapiscIO.connect method

github-actions · 2026-02-05T22:38:44Z

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

github-actions · 2026-02-05T22:40:29Z

✅ All checks passed! Ready for review.

github-actions · 2026-02-05T22:41:26Z

✅ Integration tests passed! Server validation, BadgeKeeper, and gRPC tests all working.

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 15 comments.

capiscio_sdk/connect.py

tests/unit/test_events.py

tests/unit/test_connect.py

capiscio_sdk/connect.py

Copilot AI review requested due to automatic review settings February 5, 2026 21:19

Copilot started reviewing on behalf of beonde February 5, 2026 21:19 View session

Copilot AI reviewed Feb 5, 2026

View reviewed changes

fix: require protobuf>=6.33.5 to match generated code

4e26818

fix: address Copilot review comments

7e4d991

- Fix BadgeKeeper.get_badge() -> get_current_badge() (2 places) - Fix proto import paths: from capiscio.v1 -> from capiscio_sdk._rpc.gen.capiscio.v1 - Remove unused json imports from connect.py and events.py

Copilot AI review requested due to automatic review settings February 5, 2026 21:54

Copilot started reviewing on behalf of beonde February 5, 2026 21:55 View session

Copilot AI reviewed Feb 5, 2026

View reviewed changes

test: Add unit tests for connect.py and events.py

08a3252

- Add 32 tests for connect.py (AgentIdentity, CapiscIO.connect, from_env, _Connector) - Add 28 tests for events.py (EventEmitter, global functions) - Improve patch coverage for new Let's Encrypt-style setup feature

fix: Correct patch path in test_connect_calls_connector

46d8758

Copilot AI review requested due to automatic review settings February 5, 2026 22:17

Copilot started reviewing on behalf of beonde February 5, 2026 22:18 View session

Copilot AI reviewed Feb 5, 2026

View reviewed changes

fix: Make RPC mock tests Python 3.10 compatible

323acc6

Directly set _rpc_client on connector instead of patching, avoids naming conflict between capiscio_sdk.connect module and CapiscIO.connect method

Copilot AI review requested due to automatic review settings February 5, 2026 22:38

Copilot started reviewing on behalf of beonde February 5, 2026 22:38 View session

beonde merged commit 206d90a into main Feb 5, 2026
19 checks passed

beonde deleted the feature/connect-api branch February 5, 2026 22:48

Copilot AI reviewed Feb 5, 2026

View reviewed changes

beonde mentioned this pull request Feb 6, 2026

fix: Address Copilot review comments for connect.py #27

Merged

Conversation

beonde commented Feb 5, 2026

Summary

Usage

Changes

New Modules

Proto Updates

Documentation

Two Setup Paths

Dependencies

Related PRs

Uh oh!

github-actions bot commented Feb 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Feb 5, 2026

Uh oh!

github-actions bot commented Feb 5, 2026

Uh oh!

github-actions bot commented Feb 5, 2026

Uh oh!

codecov bot commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions bot commented Feb 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Feb 5, 2026

Uh oh!

github-actions bot commented Feb 5, 2026

Uh oh!

github-actions bot commented Feb 5, 2026

Uh oh!

github-actions bot commented Feb 5, 2026

Uh oh!

github-actions bot commented Feb 5, 2026

Uh oh!

github-actions bot commented Feb 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Feb 5, 2026 •

edited

Loading