<div align="center">
<img src="https://raw.githubusercontent.com/prassanna-ravishankar/phlow/main/docs/phlow-logo.png" alt="Phlow Logo" width="400">
# Phlow
**JWT authentication middleware for AI agents with Supabase integration**
</div>
<div align="center">
[](https://pypi.org/project/phlow/)
[](https://opensource.org/licenses/MIT)
</div>
## 🎯 What is Phlow?
Phlow is authentication middleware for AI agents that's evolving into the **Agent Marketplace Platform** - enabling agents to discover, authenticate, and monetize their capabilities.
**Current: A2A Protocol + Supabase • JWT Auth • Middleware**
**Vision: The "App Store for AI Agents"**
### 🌟 Our Evolution Path
```
Phase 1: Authentication Middleware (Current)
↓
Phase 2: Agent Discovery & Registry
↓
Phase 3: Agent Marketplace Platform
```
We're building the foundational trust layer that will enable agents to securely discover, interact with, and monetize their capabilities - creating the first true marketplace for AI agent services.
## ⚡ Quick Start
```bash
pip install phlow
```
### Python Example
```python
from phlow import PhlowMiddleware, AgentCard, PhlowConfig
config = PhlowConfig(
agent_card=AgentCard(
name="My Agent",
description="Agent description",
service_url="https://my-agent.com",
skills=["chat", "analysis"],
metadata={"agent_id": "my-agent-id", "public_key": "public-key-here"}
),
private_key=os.environ["PRIVATE_KEY"],
supabase_url=os.environ["SUPABASE_URL"],
supabase_anon_key=os.environ["SUPABASE_ANON_KEY"]
)
phlow = PhlowMiddleware(config)
```
### FastAPI Middleware
```python
# Use A2A authentication with Supabase features
@app.post("/api/chat")
async def chat_endpoint(context: PhlowContext = Depends(auth_required)):
# Access agent info and Supabase client
agent = context.agent
return {"message": f"Hello from {agent.name}"}
```
[Full Setup Guide →](docs/getting-started.md)
## 🚀 Features
- **🔐 JWT Authentication** - Verify A2A Protocol JWT tokens
- **📋 Agent Storage** - Store and retrieve agent cards in Supabase
- **🛡️ RLS Helpers** - Generate basic Supabase Row Level Security policies
- **📊 Basic Audit** - Log authentication events to Supabase
- **🌐 Python Package** - Pure Python implementation
- **🔧 FastAPI Integration** - Complete middleware with dependency injection
## How It Works
```mermaid
sequenceDiagram
participant A as Agent A
participant B as Agent B
participant S as Supabase Registry
A->>A: Generate JWT with private key
A->>B: Send request + JWT + Agent ID header
B->>S: Lookup Agent A's public key
S->>B: Return AgentCard with public key
B->>B: Verify JWT signature
B->>A: Return response
```
## 📦 What's Included
```
phlow/
├── src/phlow/ # Python authentication library
├── tests/ # Test suite
├── examples/ # Example implementations
└── docs/ # Documentation
├── getting-started.md # Quick setup guide
├── a2a-compatibility.md # A2A Protocol integration
└── api-reference.md # API documentation
```
## 🏗️ How It Works
Phlow is a lightweight middleware that connects A2A Protocol JWT authentication with Supabase storage:
1. **JWT Verification** - Validates A2A Protocol tokens
2. **Agent Lookup** - Retrieves agent cards from Supabase
3. **Context Creation** - Provides agent info and Supabase client to your app
4. **Basic Logging** - Optionally logs auth events
See [Getting Started](docs/getting-started.md) for setup instructions.
## 🔧 Setup
1. **Install**: `pip install phlow`
2. **Configure**: Set up Supabase project and environment variables
3. **Initialize**: Register your agent card in Supabase
4. **Authenticate**: Add Phlow middleware to your A2A agent
[Detailed Setup Instructions →](docs/getting-started.md)
## 💡 Example: A2A Agent with Phlow Auth
```python
# A2A + Phlow Integration
from phlow import PhlowMiddleware, AgentCard, PhlowConfig
config = PhlowConfig(
agent_card=AgentCard(
name="My Agent",
description="A2A-compatible agent",
service_url="https://my-agent.com",
skills=["chat", "analysis"],
metadata={"agent_id": "my-agent-id", "public_key": "public-key-here"}
),
private_key=os.environ["PRIVATE_KEY"],
supabase_url=os.environ["SUPABASE_URL"],
supabase_anon_key=os.environ["SUPABASE_ANON_KEY"]
)
phlow = PhlowMiddleware(config)
# Use with FastAPI
from phlow.integrations.fastapi import create_phlow_dependency
auth_required = create_phlow_dependency(phlow)
@app.post("/api/a2a/message")
async def handle_message(context: PhlowContext = Depends(auth_required)):
# Process A2A message using phlow context
return {"status": "received"}
```
## 📚 Documentation
- **[Getting Started](docs/getting-started.md)** - Quick setup guide
- **[A2A Compatibility](docs/a2a-compatibility.md)** - A2A Protocol integration
- **[API Reference](docs/api-reference.md)** - Complete API docs
## 🌐 Language Support
| Language | Package | Framework Support |
|----------|---------|------------------|
| Python | `phlow` | FastAPI |
## 🚀 Roadmap & Vision
### Phase 1: Authentication Middleware (Current)
- ✅ JWT authentication for A2A Protocol
- ✅ Agent card storage in Supabase
- ✅ Basic middleware for FastAPI
- 🔄 Enhanced security and testing
### Phase 2: Agent Discovery & Registry (Next 6 months)
- 🎯 Central agent registry with search capabilities
- 🎯 Agent capability matching and discovery
- 🎯 Enhanced agent profiles and metadata
- 🎯 Agent network visualization
### Phase 3: Agent Marketplace Platform (6-18 months)
- 🎯 Agent monetization and billing
- 🎯 Usage analytics and performance metrics
- 🎯 Agent rating and reputation systems
- 🎯 Developer tools and SDK ecosystem
**Our North Star**: Create the first true marketplace where AI agents can discover, authenticate, and monetize their capabilities - making agent-to-agent commerce as simple as an API call.
## Contributing
Pull requests welcome! We're building towards our marketplace vision:
**Current Focus Areas:**
- Authentication middleware improvements
- Supabase integration enhancements
- Agent registry and discovery features
- Developer experience improvements
**Future Contribution Areas:**
- Agent marketplace features
- Monetization and billing systems
- Analytics and metrics
- Community tools and governance
**Scope**: Please keep contributions focused on authentication, agent registry, discovery, and marketplace features. Communication protocols should be contributed to the [A2A Protocol](https://github.com/a2aproject) directly.
### Quick Start
```bash
# Install dependencies
uv sync --dev
# Run all quality checks
uv run task quality
# Run tests
uv run task test
# Run E2E tests (requires Docker)
uv run task test-e2e
```
### Development Commands
```bash
uv sync --dev # Install all dependencies
uv run task test # Run all tests with coverage
uv run task test-unit # Run unit tests only
uv run task test-e2e # Run end-to-end tests (Docker required)
uv run task lint # Run linting with auto-fix
uv run task format # Format code
uv run task type-check # Run type checking
uv run task quality # Run all quality checks
uv run task build # Build distribution packages
uv run task clean # Clean build artifacts
```
### Testing
- **Unit Tests**: `uv run task test-unit` - Fast, mocked, runs in CI
- **E2E Tests**: `uv run task test-e2e` - Full stack, Docker required
## License
MIT License - see [LICENSE](LICENSE) file for details.
---
**Built with ❤️ for the A2A ecosystem**
[Get Started](docs/getting-started.md) | [A2A Compatibility](docs/a2a-compatibility.md) | [API Reference](docs/api-reference.md)
Raw data
{
"_id": null,
"home_page": null,
"name": "phlow",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "a2a, agent, authentication, jwt, middleware, phlow, supabase",
"author": "Prassanna Ravishankar",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9d/f7/16aacc152bc1375d1ed517546d29df95939f6b1b747e70bbbdcd79db330a/phlow-0.1.9.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/prassanna-ravishankar/phlow/main/docs/phlow-logo.png\" alt=\"Phlow Logo\" width=\"400\">\n\n # Phlow\n\n **JWT authentication middleware for AI agents with Supabase integration**\n</div>\n\n<div align=\"center\">\n\n[](https://pypi.org/project/phlow/)\n[](https://opensource.org/licenses/MIT)\n\n</div>\n\n## \ud83c\udfaf What is Phlow?\n\nPhlow is authentication middleware for AI agents that's evolving into the **Agent Marketplace Platform** - enabling agents to discover, authenticate, and monetize their capabilities.\n\n**Current: A2A Protocol + Supabase \u2022 JWT Auth \u2022 Middleware**\n**Vision: The \"App Store for AI Agents\"**\n\n### \ud83c\udf1f Our Evolution Path\n\n```\nPhase 1: Authentication Middleware (Current)\n \u2193\nPhase 2: Agent Discovery & Registry\n \u2193\nPhase 3: Agent Marketplace Platform\n```\n\nWe're building the foundational trust layer that will enable agents to securely discover, interact with, and monetize their capabilities - creating the first true marketplace for AI agent services.\n\n## \u26a1 Quick Start\n\n```bash\npip install phlow\n```\n\n### Python Example\n\n```python\nfrom phlow import PhlowMiddleware, AgentCard, PhlowConfig\n\nconfig = PhlowConfig(\n agent_card=AgentCard(\n name=\"My Agent\",\n description=\"Agent description\",\n service_url=\"https://my-agent.com\",\n skills=[\"chat\", \"analysis\"],\n metadata={\"agent_id\": \"my-agent-id\", \"public_key\": \"public-key-here\"}\n ),\n private_key=os.environ[\"PRIVATE_KEY\"],\n supabase_url=os.environ[\"SUPABASE_URL\"],\n supabase_anon_key=os.environ[\"SUPABASE_ANON_KEY\"]\n)\n\nphlow = PhlowMiddleware(config)\n```\n\n### FastAPI Middleware\n\n```python\n# Use A2A authentication with Supabase features\n@app.post(\"/api/chat\")\nasync def chat_endpoint(context: PhlowContext = Depends(auth_required)):\n # Access agent info and Supabase client\n agent = context.agent\n return {\"message\": f\"Hello from {agent.name}\"}\n```\n\n[Full Setup Guide \u2192](docs/getting-started.md)\n\n## \ud83d\ude80 Features\n\n- **\ud83d\udd10 JWT Authentication** - Verify A2A Protocol JWT tokens\n- **\ud83d\udccb Agent Storage** - Store and retrieve agent cards in Supabase\n- **\ud83d\udee1\ufe0f RLS Helpers** - Generate basic Supabase Row Level Security policies\n- **\ud83d\udcca Basic Audit** - Log authentication events to Supabase\n- **\ud83c\udf10 Python Package** - Pure Python implementation\n- **\ud83d\udd27 FastAPI Integration** - Complete middleware with dependency injection\n\n\n## How It Works\n\n```mermaid\nsequenceDiagram\n participant A as Agent A\n participant B as Agent B\n participant S as Supabase Registry\n\n A->>A: Generate JWT with private key\n A->>B: Send request + JWT + Agent ID header\n B->>S: Lookup Agent A's public key\n S->>B: Return AgentCard with public key\n B->>B: Verify JWT signature\n B->>A: Return response\n```\n\n## \ud83d\udce6 What's Included\n\n```\nphlow/\n\u251c\u2500\u2500 src/phlow/ # Python authentication library\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 examples/ # Example implementations\n\u2514\u2500\u2500 docs/ # Documentation\n \u251c\u2500\u2500 getting-started.md # Quick setup guide\n \u251c\u2500\u2500 a2a-compatibility.md # A2A Protocol integration\n \u2514\u2500\u2500 api-reference.md # API documentation\n```\n\n## \ud83c\udfd7\ufe0f How It Works\n\nPhlow is a lightweight middleware that connects A2A Protocol JWT authentication with Supabase storage:\n\n1. **JWT Verification** - Validates A2A Protocol tokens\n2. **Agent Lookup** - Retrieves agent cards from Supabase\n3. **Context Creation** - Provides agent info and Supabase client to your app\n4. **Basic Logging** - Optionally logs auth events\n\nSee [Getting Started](docs/getting-started.md) for setup instructions.\n\n\n## \ud83d\udd27 Setup\n\n1. **Install**: `pip install phlow`\n2. **Configure**: Set up Supabase project and environment variables\n3. **Initialize**: Register your agent card in Supabase\n4. **Authenticate**: Add Phlow middleware to your A2A agent\n\n[Detailed Setup Instructions \u2192](docs/getting-started.md)\n\n## \ud83d\udca1 Example: A2A Agent with Phlow Auth\n\n```python\n# A2A + Phlow Integration\nfrom phlow import PhlowMiddleware, AgentCard, PhlowConfig\n\nconfig = PhlowConfig(\n agent_card=AgentCard(\n name=\"My Agent\",\n description=\"A2A-compatible agent\",\n service_url=\"https://my-agent.com\",\n skills=[\"chat\", \"analysis\"],\n metadata={\"agent_id\": \"my-agent-id\", \"public_key\": \"public-key-here\"}\n ),\n private_key=os.environ[\"PRIVATE_KEY\"],\n supabase_url=os.environ[\"SUPABASE_URL\"],\n supabase_anon_key=os.environ[\"SUPABASE_ANON_KEY\"]\n)\n\nphlow = PhlowMiddleware(config)\n\n# Use with FastAPI\nfrom phlow.integrations.fastapi import create_phlow_dependency\nauth_required = create_phlow_dependency(phlow)\n\n@app.post(\"/api/a2a/message\")\nasync def handle_message(context: PhlowContext = Depends(auth_required)):\n # Process A2A message using phlow context\n return {\"status\": \"received\"}\n```\n\n## \ud83d\udcda Documentation\n\n- **[Getting Started](docs/getting-started.md)** - Quick setup guide\n- **[A2A Compatibility](docs/a2a-compatibility.md)** - A2A Protocol integration\n- **[API Reference](docs/api-reference.md)** - Complete API docs\n\n## \ud83c\udf10 Language Support\n\n| Language | Package | Framework Support |\n|----------|---------|------------------|\n| Python | `phlow` | FastAPI |\n\n## \ud83d\ude80 Roadmap & Vision\n\n### Phase 1: Authentication Middleware (Current)\n- \u2705 JWT authentication for A2A Protocol\n- \u2705 Agent card storage in Supabase\n- \u2705 Basic middleware for FastAPI\n- \ud83d\udd04 Enhanced security and testing\n\n### Phase 2: Agent Discovery & Registry (Next 6 months)\n- \ud83c\udfaf Central agent registry with search capabilities\n- \ud83c\udfaf Agent capability matching and discovery\n- \ud83c\udfaf Enhanced agent profiles and metadata\n- \ud83c\udfaf Agent network visualization\n\n### Phase 3: Agent Marketplace Platform (6-18 months)\n- \ud83c\udfaf Agent monetization and billing\n- \ud83c\udfaf Usage analytics and performance metrics\n- \ud83c\udfaf Agent rating and reputation systems\n- \ud83c\udfaf Developer tools and SDK ecosystem\n\n**Our North Star**: Create the first true marketplace where AI agents can discover, authenticate, and monetize their capabilities - making agent-to-agent commerce as simple as an API call.\n\n## Contributing\n\nPull requests welcome! We're building towards our marketplace vision:\n\n**Current Focus Areas:**\n- Authentication middleware improvements\n- Supabase integration enhancements\n- Agent registry and discovery features\n- Developer experience improvements\n\n**Future Contribution Areas:**\n- Agent marketplace features\n- Monetization and billing systems\n- Analytics and metrics\n- Community tools and governance\n\n**Scope**: Please keep contributions focused on authentication, agent registry, discovery, and marketplace features. Communication protocols should be contributed to the [A2A Protocol](https://github.com/a2aproject) directly.\n\n### Quick Start\n```bash\n# Install dependencies\nuv sync --dev\n\n# Run all quality checks\nuv run task quality\n\n# Run tests\nuv run task test\n\n# Run E2E tests (requires Docker)\nuv run task test-e2e\n```\n\n### Development Commands\n```bash\nuv sync --dev # Install all dependencies\nuv run task test # Run all tests with coverage\nuv run task test-unit # Run unit tests only\nuv run task test-e2e # Run end-to-end tests (Docker required)\nuv run task lint # Run linting with auto-fix\nuv run task format # Format code\nuv run task type-check # Run type checking\nuv run task quality # Run all quality checks\nuv run task build # Build distribution packages\nuv run task clean # Clean build artifacts\n```\n\n### Testing\n- **Unit Tests**: `uv run task test-unit` - Fast, mocked, runs in CI\n- **E2E Tests**: `uv run task test-e2e` - Full stack, Docker required\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n**Built with \u2764\ufe0f for the A2A ecosystem**\n\n[Get Started](docs/getting-started.md) | [A2A Compatibility](docs/a2a-compatibility.md) | [API Reference](docs/api-reference.md)\n",
"bugtrack_url": null,
"license": null,
"summary": "Simple Python library for Phlow authentication",
"version": "0.1.9",
"project_urls": {
"Documentation": "https://prassanna.io/phlow/",
"Issues": "https://github.com/prassanna-ravishankar/phlow/issues",
"Source": "https://github.com/prassanna-ravishankar/phlow"
},
"split_keywords": [
"a2a",
" agent",
" authentication",
" jwt",
" middleware",
" phlow",
" supabase"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "49b8f4483571aeb365900e66b78f2d3616ffb457c74af7e482ccc35bfb9bd0a6",
"md5": "f39301caf81d5d7ba09d522a665a0478",
"sha256": "2638749b2f6ed10534c527213ca403b277879694a295d9698b8a6c28201e7caf"
},
"downloads": -1,
"filename": "phlow-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f39301caf81d5d7ba09d522a665a0478",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 49457,
"upload_time": "2025-08-02T14:12:48",
"upload_time_iso_8601": "2025-08-02T14:12:48.876392Z",
"url": "https://files.pythonhosted.org/packages/49/b8/f4483571aeb365900e66b78f2d3616ffb457c74af7e482ccc35bfb9bd0a6/phlow-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9df716aacc152bc1375d1ed517546d29df95939f6b1b747e70bbbdcd79db330a",
"md5": "b85a86e130039a14326e1d39709a96cc",
"sha256": "41ba79d15f8b4ae49829d179c863dd47c699a8b068f16ecc376ee96f14b6a856"
},
"downloads": -1,
"filename": "phlow-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "b85a86e130039a14326e1d39709a96cc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 64004,
"upload_time": "2025-08-02T14:12:49",
"upload_time_iso_8601": "2025-08-02T14:12:49.919380Z",
"url": "https://files.pythonhosted.org/packages/9d/f7/16aacc152bc1375d1ed517546d29df95939f6b1b747e70bbbdcd79db330a/phlow-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-02 14:12:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "prassanna-ravishankar",
"github_project": "phlow",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "phlow"
}
JSON
