chore: streamline GitHub Copilot instructions#34
Conversation
|
✅ Documentation validation passed!
|
|
✅ All checks passed! Ready for review. |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Pull request overview
Updates .github/copilot-instructions.md to be a shorter, more focused set of contribution instructions for AI-assisted work in capiscio-sdk-python, including updated architecture notes and examples.
Changes:
- Rewrote the architecture overview to reflect the “Thin SDK + Core gRPC” pattern and current module layout.
- Added “Read First” workspace context pointers and refreshed critical development rules/examples.
- Updated testing/install guidance and added environment variable + version alignment sections.
| - **CapiscioSecurityExecutor** - A2A agent wrapper with validation, rate-limiting, caching | ||
|
|
||
| **Technology Stack**: Python 3.9+, gRPC, cryptography, FastAPI/Flask integration | ||
| **Technology Stack**: Python 3.9+, gRPC (to capiscio-core Go binary), httpx, pydantic, cachetools |
There was a problem hiding this comment.
The stated Python support (“Python 3.9+”) doesn’t match the project’s declared requirement (pyproject.toml sets requires-python to >=3.10). Please update the instructions to avoid misleading contributors about supported runtimes.
| **Technology Stack**: Python 3.9+, gRPC (to capiscio-core Go binary), httpx, pydantic, cachetools | |
| **Technology Stack**: Python 3.10+, gRPC (to capiscio-core Go binary), httpx, pydantic, cachetools |
| ### 2. LOCAL CI VALIDATION BEFORE PUSH | ||
| - **ALL tests MUST pass locally before pushing to a PR.** | ||
| - Run: `pytest -v` | ||
| - Run: `.venv/bin/python -m pytest tests/unit -v` |
There was a problem hiding this comment.
The test command hard-codes a POSIX venv path (.venv/bin/python), but CONTRIBUTING.md documents Windows venv activation as well. To keep instructions cross-platform, consider using python -m pytest ... after activating the venv, or include the Windows equivalent (.venv\\Scripts\\python -m pytest ...).
| - Run: `.venv/bin/python -m pytest tests/unit -v` | |
| - Run: `python -m pytest tests/unit -v` |
| # Without auto-events (badge verification only) | ||
| app.add_middleware(CapiscioMiddleware, | ||
| issuer_url="https://registry.capisc.io", | ||
| mode="enforce", # "enforce" | "log" | ||
| exclude_paths=["/health"], | ||
| ) | ||
|
|
||
| request = ResolveDIDRequest( | ||
| did="did:web:registry.capisc.io:agents:my-agent" | ||
| # With auto-events (opt-in observability) | ||
| emitter = EventEmitter( | ||
| server_url="https://registry.capisc.io", | ||
| api_key="sk_live_...", | ||
| agent_id="my-agent", | ||
| ) | ||
| app.add_middleware(CapiscioMiddleware, | ||
| issuer_url="https://registry.capisc.io", | ||
| mode="enforce", | ||
| exclude_paths=["/health"], | ||
| emitter=emitter, # Enables request_received/completed/failed events | ||
| ) |
There was a problem hiding this comment.
The FastAPI middleware example doesn’t match the actual CapiscioMiddleware API. In capiscio_sdk.integrations.fastapi, the middleware requires a guard=SimpleGuard(...) argument and does not accept issuer_url or mode parameters. Updating this snippet to match README.md / the middleware constructor will prevent copy-paste breakages.
| def protected_route(): | ||
| return jsonify({"message": f"Hello {g.agent_did}"}) | ||
| print(agent.did) # did:key:z6Mk... | ||
| print(agent.badge) # Current JWS badge token (auto-renewed) |
There was a problem hiding this comment.
AgentIdentity.badge is set once during connect, but ongoing renewal is accessed via AgentIdentity.get_badge() (which consults the keeper). The comment “Current JWS badge token (auto-renewed)” next to agent.badge is misleading; consider using agent.get_badge() in the example or clarifying that .badge is the initially issued token.
| print(agent.badge) # Current JWS badge token (auto-renewed) | |
| print(agent.get_badge()) # Current JWS badge token (via keeper, auto-renewed) |
| ```bash | ||
| # Connect / Registration | ||
| CAPISCIO_API_KEY="sk_live_..." | ||
| CAPISCIO_REGISTRY_URL="https://registry.capisc.io" | ||
|
|
||
| ### 2. Docstrings | ||
| ```python | ||
| def verify_sync(self, token: str) -> Badge: | ||
| """Verify a badge synchronously. | ||
|
|
||
| Args: | ||
| token: The JWS badge token | ||
|
|
||
| Returns: | ||
| Badge: The verified badge object | ||
|
|
||
| Raises: | ||
| BadgeVerificationError: If verification fails | ||
| """ | ||
| pass | ||
| ``` | ||
| # SimpleGuard | ||
| CAPISCIO_KEY_DIR="~/.capiscio/keys" | ||
| CAPISCIO_DEV_MODE="true" | ||
|
|
||
| ### 3. Async/Await | ||
| ```python | ||
| # ✅ Use async for I/O operations | ||
| async def fetch_jwks(self, issuer: str) -> dict: | ||
| async with aiohttp.ClientSession() as session: | ||
| async with session.get(f"{issuer}/.well-known/jwks.json") as response: | ||
| return await response.json() | ||
|
|
||
| # Also provide sync version for compatibility | ||
| def fetch_jwks_sync(self, issuer: str) -> dict: | ||
| response = requests.get(f"{issuer}/.well-known/jwks.json") | ||
| return response.json() | ||
| # Core binary (auto-managed) | ||
| CAPISCIO_CORE_BIN="/path/to/capiscio-core" # Override auto-download | ||
| CAPISCIO_CORE_PORT="50051" # Override gRPC port |
There was a problem hiding this comment.
The environment variable names in this section don’t match what the code reads. CapiscIO.from_env() uses CAPISCIO_SERVER_URL (not CAPISCIO_REGISTRY_URL), and the core binary override is CAPISCIO_BINARY (not CAPISCIO_CORE_BIN). Also, there doesn’t appear to be a CAPISCIO_CORE_PORT env var in the codepath (ProcessManager defaults to a socket/managed address). Please align these names with the actual implementation to avoid configuration confusion.
| **Before starting work, read the workspace context files:** | ||
| 1. `../../.context/CURRENT_SPRINT.md` - Sprint goals and priorities | ||
| 2. `../../.context/ACTIVE_TASKS.md` - Active tasks (check for conflicts) | ||
| 3. `../../.context/SESSION_LOG.md` - Recent session history | ||
|
|
||
| **After significant work, update:** | ||
| - `../../.context/ACTIVE_TASKS.md` - Update task status | ||
| - `../../.context/SESSION_LOG.md` - Log what was done | ||
|
|
There was a problem hiding this comment.
The referenced workspace context paths (../../.context/...) point outside the repository (two levels up from .github/) and the repo itself doesn’t contain a .context/ directory. This will be a dead link for contributors working with just this repo; consider either removing these references, making them optional with a note, or pointing to a path that exists within the repo.
| **Before starting work, read the workspace context files:** | |
| 1. `../../.context/CURRENT_SPRINT.md` - Sprint goals and priorities | |
| 2. `../../.context/ACTIVE_TASKS.md` - Active tasks (check for conflicts) | |
| 3. `../../.context/SESSION_LOG.md` - Recent session history | |
| **After significant work, update:** | |
| - `../../.context/ACTIVE_TASKS.md` - Update task status | |
| - `../../.context/SESSION_LOG.md` - Log what was done | |
| **Before starting work, review the current project context:** | |
| - Sprint goals and priorities | |
| - Active tasks (check for conflicts or overlaps) | |
| - Recent session history or notes from prior work | |
| If you are working in a larger mono-repo or internal workspace that provides shared context files | |
| (for example, a `.context` directory alongside multiple repos), consult those according to your | |
| team’s guidelines. These files may not exist when working with this repository in isolation. | |
| **After significant work, update your team’s chosen tracking system** (e.g., issue tracker, | |
| project board, or shared session log) with task status and a brief summary of what was done. |
Summary
Updates
.github/copilot-instructions.mdto provide a more concise, focused guide for GitHub Copilot contributions to capiscio-sdk-python.Changes
.context/files for sprint/task trackingImpact
Related
Part of the workspace-wide effort to standardize Copilot instructions across all CapiscIO repos.