afd 0.1.0__tar.gz

afd-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Dependencies
+node_modules/
+.pnpm-store/
+package-lock.json
+
+# Build outputs
+dist/
+*.tsbuildinfo
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+.eggs/
+*.egg-info/
+*.egg
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# Test coverage
+coverage/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Misc
+*.plan.md
+!PLAN/**/*.plan.md
+!archive/**/*.plan.md
+.cursor/
+nul

afd-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: afd
+Version: 0.1.0
+Summary: Agent-First Development toolkit for Python
+Project-URL: Homepage, https://github.com/Falkicon/afd
+Project-URL: Documentation, https://github.com/Falkicon/afd/tree/main/python
+Project-URL: Repository, https://github.com/Falkicon/afd
+Author-email: Falkicon <falkicon@example.com>
+License-Expression: MIT
+Keywords: afd,agent,agent-first,ai,cli,commands,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Provides-Extra: all
+Requires-Dist: click>=8.0; extra == 'all'
+Requires-Dist: fastmcp>=0.1.0; extra == 'all'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'all'
+Requires-Dist: pytest>=8.0; extra == 'all'
+Requires-Dist: rich>=13.0; extra == 'all'
+Provides-Extra: cli
+Requires-Dist: click>=8.0; extra == 'cli'
+Requires-Dist: fastmcp>=0.1.0; extra == 'cli'
+Requires-Dist: rich>=13.0; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: click>=8.0; extra == 'dev'
+Requires-Dist: fastmcp>=0.1.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: rich>=13.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: server
+Requires-Dist: fastmcp>=0.1.0; extra == 'server'
+Provides-Extra: testing
+Requires-Dist: pytest-asyncio>=0.23; extra == 'testing'
+Requires-Dist: pytest>=8.0; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# AFD - Agent-First Development for Python
+
+A Python toolkit for building applications with the Agent-First Development methodology.
+
+## What is AFD?
+
+**Agent-First Development** is a software development methodology where AI agents are treated as first-class users from day one. Instead of building UI first and adding API/agent access later, AFD inverts this:
+
+```
+Traditional:  UI → API → Agent Access (afterthought)
+Agent-First:  Commands → Validation → UI (surface)
+```
+
+## Installation
+
+```bash
+# Core types only
+pip install afd
+
+# With MCP server support
+pip install afd[server]
+
+# With CLI
+pip install afd[cli]
+
+# With testing utilities
+pip install afd[testing]
+
+# Everything
+pip install afd[all]
+```
+
+## Quick Start
+
+### Define a Command
+
+```python
+from afd import CommandResult, success, error
+from afd.server import define_command
+from pydantic import BaseModel
+
+class Todo(BaseModel):
+    id: str
+    title: str
+    done: bool = False
+
+@define_command(
+    name="todo.create",
+    description="Create a new todo item",
+)
+async def create_todo(title: str) -> CommandResult[Todo]:
+    todo = Todo(id="todo-1", title=title)
+    return success(
+        data=todo,
+        reasoning="Created new todo with default status",
+    )
+```
+
+### Create an MCP Server
+
+```python
+from afd.server import create_server
+
+server = create_server(
+    name="todo-app",
+    version="1.0.0",
+)
+
+@server.command(
+    name="todo.create",
+    description="Create a todo",
+)
+async def create_todo(input):
+    todo = Todo(id="todo-1", title=input["title"])
+    return success(data=todo)
+
+# Run the server (stdio for VS Code/Cursor)
+server.run()
+```
+
+### Test Your Commands
+
+```python
+import pytest
+from afd.testing import assert_success
+
+# Use the mock_server fixture
+async def test_create_todo(mock_server):
+    @mock_server.command("todo.create")
+    async def handler(input):
+        from afd import success
+        return success({"id": "1", "title": input["title"]})
+
+    result = await mock_server.execute("todo.create", {"title": "Test"})
+
+    data = assert_success(result)
+    assert data["title"] == "Test"
+```
+
+## Core Types
+
+### CommandResult
+
+The standard return type for all commands:
+
+```python
+from afd import CommandResult, success, error
+
+# Successful result
+result = success(
+    data={"id": "123"},
+    reasoning="Created successfully",
+    confidence=0.95,
+)
+
+# Error result
+result = error(
+    code="NOT_FOUND",
+    message="Resource not found",
+    suggestion="Check the ID and try again",
+)
+```
+
+### UX-Enabling Fields
+
+AFD results include optional fields that enable rich agent experiences:
+
+| Field          | Purpose                                |
+| -------------- | -------------------------------------- |
+| `confidence`   | 0-1 score for UI confidence indicators |
+| `reasoning`    | Explains "why" for transparency        |
+| `sources`      | Attribution for verification           |
+| `plan`         | Multi-step operation visibility        |
+| `alternatives` | Other options considered               |
+| `warnings`     | Non-fatal issues to surface            |
+
+## Packages
+
+| Extra       | Contents                                                             |
+| ----------- | -------------------------------------------------------------------- |
+| (core)      | `CommandResult`, `success()`, `error()`, error types, metadata types |
+| `[server]`  | MCP server factory, `@define_command`, `create_server()`             |
+| `[cli]`     | Click-based CLI for connecting to MCP servers                        |
+| `[testing]` | `mock_server` fixture, assertions, `MockTransport`                   |
+
+## Related
+
+- [AFD TypeScript](../packages/) - Original TypeScript implementation
+- [AFD Philosophy](../docs/philosophy.md) - Why AFD?
+- [Command Schema Guide](../docs/command-schema-guide.md) - Designing commands
+
+## License
+
+MIT

afd-0.1.0/README.md

@@ -0,0 +1,154 @@
+# AFD - Agent-First Development for Python
+
+A Python toolkit for building applications with the Agent-First Development methodology.
+
+## What is AFD?
+
+**Agent-First Development** is a software development methodology where AI agents are treated as first-class users from day one. Instead of building UI first and adding API/agent access later, AFD inverts this:
+
+```
+Traditional:  UI → API → Agent Access (afterthought)
+Agent-First:  Commands → Validation → UI (surface)
+```
+
+## Installation
+
+```bash
+# Core types only
+pip install afd
+
+# With MCP server support
+pip install afd[server]
+
+# With CLI
+pip install afd[cli]
+
+# With testing utilities
+pip install afd[testing]
+
+# Everything
+pip install afd[all]
+```
+
+## Quick Start
+
+### Define a Command
+
+```python
+from afd import CommandResult, success, error
+from afd.server import define_command
+from pydantic import BaseModel
+
+class Todo(BaseModel):
+    id: str
+    title: str
+    done: bool = False
+
+@define_command(
+    name="todo.create",
+    description="Create a new todo item",
+)
+async def create_todo(title: str) -> CommandResult[Todo]:
+    todo = Todo(id="todo-1", title=title)
+    return success(
+        data=todo,
+        reasoning="Created new todo with default status",
+    )
+```
+
+### Create an MCP Server
+
+```python
+from afd.server import create_server
+
+server = create_server(
+    name="todo-app",
+    version="1.0.0",
+)
+
+@server.command(
+    name="todo.create",
+    description="Create a todo",
+)
+async def create_todo(input):
+    todo = Todo(id="todo-1", title=input["title"])
+    return success(data=todo)
+
+# Run the server (stdio for VS Code/Cursor)
+server.run()
+```
+
+### Test Your Commands
+
+```python
+import pytest
+from afd.testing import assert_success
+
+# Use the mock_server fixture
+async def test_create_todo(mock_server):
+    @mock_server.command("todo.create")
+    async def handler(input):
+        from afd import success
+        return success({"id": "1", "title": input["title"]})
+
+    result = await mock_server.execute("todo.create", {"title": "Test"})
+
+    data = assert_success(result)
+    assert data["title"] == "Test"
+```
+
+## Core Types
+
+### CommandResult
+
+The standard return type for all commands:
+
+```python
+from afd import CommandResult, success, error
+
+# Successful result
+result = success(
+    data={"id": "123"},
+    reasoning="Created successfully",
+    confidence=0.95,
+)
+
+# Error result
+result = error(
+    code="NOT_FOUND",
+    message="Resource not found",
+    suggestion="Check the ID and try again",
+)
+```
+
+### UX-Enabling Fields
+
+AFD results include optional fields that enable rich agent experiences:
+
+| Field          | Purpose                                |
+| -------------- | -------------------------------------- |
+| `confidence`   | 0-1 score for UI confidence indicators |
+| `reasoning`    | Explains "why" for transparency        |
+| `sources`      | Attribution for verification           |
+| `plan`         | Multi-step operation visibility        |
+| `alternatives` | Other options considered               |
+| `warnings`     | Non-fatal issues to surface            |
+
+## Packages
+
+| Extra       | Contents                                                             |
+| ----------- | -------------------------------------------------------------------- |
+| (core)      | `CommandResult`, `success()`, `error()`, error types, metadata types |
+| `[server]`  | MCP server factory, `@define_command`, `create_server()`             |
+| `[cli]`     | Click-based CLI for connecting to MCP servers                        |
+| `[testing]` | `mock_server` fixture, assertions, `MockTransport`                   |
+
+## Related
+
+- [AFD TypeScript](../packages/) - Original TypeScript implementation
+- [AFD Philosophy](../docs/philosophy.md) - Why AFD?
+- [Command Schema Guide](../docs/command-schema-guide.md) - Designing commands
+
+## License
+
+MIT

afd-0.1.0/examples/__init__.py

@@ -0,0 +1,9 @@
+"""AFD Examples.
+
+This package contains example code demonstrating how to use AFD.
+
+Examples:
+    - todo_server.py: A complete MCP server for managing todos
+    - test_example.py: Testing patterns with AFD assertions
+    - client_usage.py: Using the transport layer programmatically
+"""

afd-0.1.0/examples/client_usage.py

@@ -0,0 +1,112 @@
+"""Example: Using the AFD CLI.
+
+This script demonstrates how to use the AFD client library
+to connect to and interact with MCP servers programmatically.
+"""
+
+import asyncio
+from afd.transports import MockTransport, TransportConfig
+from afd import success
+
+
+async def main():
+    """Demonstrate AFD client usage."""
+    
+    # ==============================================================================
+    # Create a MockTransport for demonstration
+    # ==============================================================================
+    
+    transport = MockTransport(
+        config=TransportConfig(
+            timeout_ms=5000,
+        )
+    )
+    
+    # Register some mock tools
+    async def echo(args):
+        return success({"message": args.get("text", "Hello!")})
+    
+    async def add_numbers(args):
+        a = args.get("a", 0)
+        b = args.get("b", 0)
+        return success({"result": a + b})
+    
+    transport.register_tool(
+        name="echo",
+        handler=echo,
+        description="Echo back a message",
+    )
+    
+    transport.register_tool(
+        name="math.add",
+        handler=add_numbers,
+        description="Add two numbers",
+    )
+    
+    # ==============================================================================
+    # Connect to the server
+    # ==============================================================================
+    
+    print("Connecting to server...")
+    await transport.connect()
+    print(f"  State: {transport.state.value}")
+    print()
+    
+    # ==============================================================================
+    # List available tools
+    # ==============================================================================
+    
+    print("Available tools:")
+    tools = await transport.list_tools()
+    for tool in tools:
+        print(f"  - {tool.name}: {tool.description}")
+    print()
+    
+    # ==============================================================================
+    # Call tools
+    # ==============================================================================
+    
+    print("Calling 'echo' tool...")
+    result = await transport.call_tool("echo", {"text": "Hello, AFD!"})
+    print(f"  Success: {result.success}")
+    print(f"  Data: {result.data}")
+    print()
+    
+    print("Calling 'math.add' tool...")
+    result = await transport.call_tool("math.add", {"a": 42, "b": 58})
+    print(f"  Success: {result.success}")
+    print(f"  Data: {result.data}")
+    print()
+    
+    # ==============================================================================
+    # Call a non-existent tool (demonstrates error handling)
+    # ==============================================================================
+    
+    print("Calling non-existent tool...")
+    try:
+        result = await transport.call_tool("does.not.exist", {})
+        print(f"  Success: {result.success}")
+    except Exception as e:
+        print(f"  Error (expected): {type(e).__name__}: {e}")
+    print()
+    
+    # ==============================================================================
+    # View call history (MockTransport feature)
+    # ==============================================================================
+    
+    print("Call history:")
+    for call in transport.calls:
+        print(f"  {call.tool_name}: {call.arguments}")
+    print()
+    
+    # ==============================================================================
+    # Disconnect
+    # ==============================================================================
+    
+    print("Disconnecting...")
+    await transport.disconnect()
+    print(f"  State: {transport.state.value}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())