Skip to content

docs(keycardai): reconcile Python version and add compatibility documentation #62

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Larry-Osakwe wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(keycardai): reconcile Python version and add compatibility documentation #62

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 77 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,85 @@ A collection of Python packages for Keycard services, organized as a uv workspac

## Requirements

- **Python 3.9 or greater**
- **Python 3.10 or greater**
- Virtual environment (recommended)

## Known Limitations & Non-Goals

### Current Limitations

- **Alpha Status**: All packages are in early development (`Development Status :: 3 - Alpha`). APIs may change between minor versions.
- **FastMCP 3.x Not Supported**: The `keycardai-mcp-fastmcp` package is pinned to FastMCP 2.x due to breaking async API changes in FastMCP 3.0 (see [PR #49](https://github.com/keycardai/python-sdk/pull/49)). Support for 3.x will be evaluated once the API stabilizes.
- **MCP Protocol Version**: Tested against MCP protocol version as implemented by `mcp>=1.13.1`. Newer MCP protocol versions may introduce incompatibilities.

### Non-Goals

- **Standalone Identity Provider**: Keycard SDKs are designed to integrate with Keycard's hosted identity service, not to provide standalone identity management.
Copy link
Collaborator

@kamil-keycard kamil-keycard Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't quite know what we mean by standalone identity provider here. Do you mean integrate directly with third-party providers?

- **Multi-Language Support**: This SDK is Python-only. Other language SDKs are separate projects.
- **Offline Operation**: All authentication flows require network connectivity to Keycard services.

## Compatibility Matrix

### Python Version Support

| Python Version | Status |
|---------------|--------|
| 3.9 | Not Supported |
| 3.10 | Supported (minimum) |
| 3.11 | Supported |
| 3.12 | Supported |
| 3.13 | Supported |

### Key Dependency Constraints

| Package | Dependency | Version Constraint | Rationale |
|---------|------------|-------------------|-----------|
| `keycardai-mcp-fastmcp` | `fastmcp` | `>=2.13.0,<3.0.0` | FastMCP 3.x has breaking async API changes. Constraint will be lifted when migration is complete. |
| All packages | `pydantic` | `>=2.11.7` | No upper bound - Pydantic 2.x maintains backward compatibility. |
| All packages | `httpx` | `>=0.27.2` | No upper bound - httpx follows semver. |
| `keycardai-mcp` | `mcp` | `>=1.13.1` | No upper bound - API is protocol-defined. |

### Why No Upper Bounds on Most Dependencies?

Following Python packaging best practices:
1. **Upper bounds cause resolver conflicts** in end-user projects when multiple packages specify conflicting ranges.
2. **Well-maintained libraries** (pydantic, httpx) follow semantic versioning and maintain backward compatibility.
3. **Testing against latest** via CI catches issues before users encounter them.

## Versioning & Breaking Changes

### Versioning Strategy

All packages follow [Semantic Versioning](https://semver.org/):

- **MAJOR.MINOR.PATCH** (e.g., `0.15.0`)
- During `0.x.y` development:
- **MINOR** bumps (`0.x.0`) may contain breaking changes
- **PATCH** bumps (`0.x.y`) are backward-compatible bug fixes

### Alpha Status (`0.x.y`)
Copy link
Collaborator

@kamil-keycard kamil-keycard Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this, nice.


All packages are currently in alpha status. This means:

1. **API Stability**: Public APIs may change between minor versions
2. **Documentation**: APIs are documented but may evolve
3. **Production Use**: Suitable for early adopters comfortable with potential migration work

### When Will Packages Reach 1.0?

Packages will graduate to `1.0.0` when:
- Public API is stable and well-documented
- Comprehensive test coverage exists
- Production usage validates the design
- No planned breaking changes for foreseeable future

### Breaking Change Policy

1. **Breaking changes** are documented in CHANGELOG.md with migration guides
Copy link
Collaborator

@kamil-keycard kamil-keycard Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Its alpha I would just say expect breaking changes.

2. **Deprecation warnings** will be added before removal where feasible
3. **Commit messages** use `!` suffix (e.g., `feat!:`) for breaking changes
4. **Release notes** highlight breaking changes prominently

## Setup Guide

### Option 1: Using uv (Recommended)
Expand Down
5 changes: 5 additions & 0 deletions packages/agents/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@

Framework-agnostic agent service SDK for A2A (Agent-to-Agent) delegation with Keycard OAuth authentication.

## Requirements

- **Python 3.10 or greater**
- Virtual environment (recommended)

## Features

- 🔐 **Built-in OAuth**: Automatic JWKS validation, token exchange, delegation chains
Expand Down
2 changes: 1 addition & 1 deletion packages/mcp-fastmcp/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ A Python package that provides seamless integration between Keycard and FastMCP

## Requirements

- **Python 3.9 or greater**
- **Python 3.10 or greater**
- Virtual environment (recommended)

## Setup Guide
Expand Down
2 changes: 1 addition & 1 deletion packages/mcp/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ A comprehensive Python SDK for Model Context Protocol (MCP) functionality that s

## Requirements

- **Python 3.9 or greater**
- **Python 3.10 or greater**
- Virtual environment (recommended)

## Setup Guide
Expand Down