nexus-a2a 0.1.0__tar.gz

nexus_a2a-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.Python
+
+# Virtual environment (uv creates this)
+.venv/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Type checking cache
+.mypy_cache/
+.ruff_cache/
+
+# Test coverage
+.coverage
+htmlcov/
+
+# IDE
+.vscode/settings.json
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

nexus_a2a-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

nexus_a2a-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: nexus-a2a
+Version: 0.1.0
+Summary: A developer-friendly Python package for building AI agent-to-agent (A2A) communication with ease.
+Project-URL: Homepage, https://github.com/yourusername/nexus-a2a
+Project-URL: Documentation, https://github.com/yourusername/nexus-a2a#readme
+Project-URL: Issues, https://github.com/yourusername/nexus-a2a/issues
+Author-email: Your Name <you@example.com>
+License: MIT
+Keywords: a2a,agent,ai,llm,multi-agent,protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Provides-Extra: all
+Requires-Dist: asyncpg>=0.29; extra == 'all'
+Requires-Dist: redis>=5.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# nexus-a2a
+
+A developer-friendly Python package for building AI agent-to-agent (A2A) communication with ease.
+
+## Install
+
+```bash
+pip install nexus-a2a
+```
+
+## Quick start
+
+```python
+from nexus_a2a import agent, AgentNetwork
+
+@agent(name="researcher", skills=["search"])
+class ResearchAgent:
+    async def run(self, task):
+        return f"Result for: {task}"
+```
+
+## Status
+🚧 Active development — v0.1.0 alpha

nexus_a2a-0.1.0/README.md

@@ -0,0 +1,23 @@
+# nexus-a2a
+
+A developer-friendly Python package for building AI agent-to-agent (A2A) communication with ease.
+
+## Install
+
+```bash
+pip install nexus-a2a
+```
+
+## Quick start
+
+```python
+from nexus_a2a import agent, AgentNetwork
+
+@agent(name="researcher", skills=["search"])
+class ResearchAgent:
+    async def run(self, task):
+        return f"Result for: {task}"
+```
+
+## Status
+🚧 Active development — v0.1.0 alpha

nexus_a2a-0.1.0/main.py

@@ -0,0 +1,6 @@
+def main():
+    print("Hello from nexus-a2a!")
+
+
+if __name__ == "__main__":
+    main()

nexus_a2a-0.1.0/nexus_a2a/__init__.py

@@ -0,0 +1,60 @@
+"""
+nexus_a2a — Developer-friendly A2A multi-agent communication for Python.
+
+Public API for Phase 1. Import everything you need from here:
+
+    from nexus_a2a import agent, get_card
+    from nexus_a2a import AgentCard, AgentSkill, AgentCapabilities
+    from nexus_a2a import Task, TaskState, Message, Artifact, Part
+"""
+
+# ── Version ───────────────────────────────────────────────────────────────────
+__version__ = "0.1.0"
+
+# ── Decorator — the primary developer entry point ─────────────────────────────
+from nexus_a2a.decorators import agent, get_card
+
+# ── Agent models ──────────────────────────────────────────────────────────────
+from nexus_a2a.models.agent import (
+    AgentAuthentication,
+    AgentCapabilities,
+    AgentCard,
+    AgentSkill,
+    AuthScheme,
+    InputMode,
+    OutputMode,
+)
+
+# ── Task models ───────────────────────────────────────────────────────────────
+from nexus_a2a.models.task import (
+    Artifact,
+    Message,
+    MessageRole,
+    Part,
+    PartType,
+    Task,
+    TaskState,
+)
+
+# ── What gets exported when someone does: from nexus_a2a import * ─────────────
+__all__ = [
+    # Decorator
+    "agent",
+    "get_card",
+    # Agent models
+    "AgentCard",
+    "AgentSkill",
+    "AgentCapabilities",
+    "AgentAuthentication",
+    "AuthScheme",
+    "InputMode",
+    "OutputMode",
+    # Task models
+    "Task",
+    "TaskState",
+    "Message",
+    "MessageRole",
+    "Part",
+    "PartType",
+    "Artifact",
+]

nexus_a2a-0.1.0/nexus_a2a/decorators.py

@@ -0,0 +1,210 @@
+"""
+nexus_a2a/decorators.py
+
+The @agent decorator — the primary entry point for developers.
+Wraps a class and automatically generates an AgentCard from its metadata.
+
+Usage:
+    @agent(
+        name="ResearchAgent",
+        description="Searches the web and summarises results.",
+        skills=[{"id": "search", "name": "Web search", "description": "..."}],
+        url="http://localhost:8001",
+    )
+    class ResearchAgent:
+        async def run(self, task: Task) -> str:
+            return "result"
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from typing import Any, Callable, TypeVar, overload, cast
+
+from nexus_a2a.models.agent import (
+    AgentAuthentication,
+    AgentCapabilities,
+    AgentCard,
+    AgentSkill,
+    AuthScheme,
+)
+
+# The decorated class can be any type
+C = TypeVar("C", bound=type)
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Attribute name we attach to the class so other layers can read the card
+_AGENT_CARD_ATTR = "__nexus_agent_card__"
+
+
+# ── Internal helpers ──────────────────────────────────────────────────────────
+
+def _build_skill(raw: dict[str, Any] | AgentSkill) -> AgentSkill:
+    """Accept either an AgentSkill instance or a plain dict and return AgentSkill."""
+    if isinstance(raw, AgentSkill):
+        return raw
+    return AgentSkill(**raw)
+
+
+def _has_async_run(cls: type) -> bool:
+    """Return True if the class has an async method named 'run'."""
+    method = getattr(cls, "run", None)
+    return method is not None and inspect.iscoroutinefunction(method)
+
+
+# ── Public decorator ──────────────────────────────────────────────────────────
+
+@overload
+def agent(cls: C) -> C: ...  # called as @agent (no parentheses)
+
+@overload
+def agent(
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    version: str = "0.1.0",
+    url: str = "http://localhost:8000",
+    skills: list[dict[str, Any] | AgentSkill] | None = None,
+    streaming: bool = False,
+    push_notifications: bool = False,
+    auth_scheme: AuthScheme = AuthScheme.NONE,
+) -> Callable[[C], C]: ...   # called as @agent(...) with arguments
+
+
+def agent(
+    cls: C | None = None,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    version: str = "0.1.0",
+    url: str = "http://localhost:8000",
+    skills: list[dict[str, Any] | AgentSkill] | None = None,
+    streaming: bool = False,
+    push_notifications: bool = False,
+    auth_scheme: AuthScheme = AuthScheme.NONE,
+) -> C | Callable[[C], C]:
+    """
+    Class decorator that registers a class as an A2A-compatible agent
+    and automatically generates its AgentCard.
+
+    Can be used in two ways:
+
+    1. With arguments (recommended):
+        @agent(
+            name="Summariser",
+            description="Summarises long documents.",
+            skills=[{"id": "summarise", "name": "Summarise", "description": "..."}],
+            url="http://localhost:8001",
+        )
+        class SummariserAgent:
+            async def run(self, task): ...
+
+    2. Without arguments (uses class name and docstring as defaults):
+        @agent
+        class SummariserAgent:
+            \"\"\"Summarises long documents.\"\"\"
+            async def run(self, task): ...
+
+    After decoration, the class gains:
+        - SummariserAgent.__nexus_agent_card__  →  AgentCard instance
+        - SummariserAgent.get_agent_card()      →  returns the AgentCard
+
+    Raises:
+        TypeError:  If the class does not have an async `run` method.
+        ValueError: If name or description cannot be resolved.
+    """
+
+    def decorator(klass: C) -> C:
+        # ── Resolve metadata ──────────────────────────────────────────────────
+        resolved_name = name or klass.__name__
+        resolved_desc = (
+            description
+            or (inspect.getdoc(klass))           # use docstring if available
+            or f"A2A agent: {resolved_name}"     # fallback
+        )
+
+        if not resolved_desc.strip():
+            raise ValueError(
+                f"@agent on '{resolved_name}': provide a description= "
+                "or add a docstring to the class."
+            )
+
+        # ── Validate the class has async run() ───────────────────────────────
+        if not _has_async_run(klass):
+            raise TypeError(
+                f"@agent on '{resolved_name}': the class must define "
+                "'async def run(self, task)' method."
+            )
+
+        # ── Build skills list ─────────────────────────────────────────────────
+        built_skills: list[AgentSkill] = [
+            _build_skill(s) for s in (skills or [])
+        ]
+
+        # ── Build AgentCard ───────────────────────────────────────────────────
+        card = AgentCard(
+            name=resolved_name,
+            description=resolved_desc,
+            version=version,
+            url=url,  # type: ignore[arg-type]  # Pydantic coerces str → HttpUrl
+            skills=built_skills,
+            capabilities=AgentCapabilities(
+                streaming=streaming,
+                push_notifications=push_notifications,
+            ),
+            authentication=AgentAuthentication(scheme=auth_scheme),
+        )
+
+        # ── Attach card to the class ──────────────────────────────────────────
+        setattr(klass, _AGENT_CARD_ATTR, card)
+
+        # ── Add helper class method ───────────────────────────────────────────
+        @classmethod  # type: ignore[misc]
+        def get_agent_card(klass_inner: type) -> AgentCard:
+            """Return the AgentCard generated by @agent."""
+            return cast(AgentCard, getattr(klass_inner, _AGENT_CARD_ATTR))
+
+        klass.get_agent_card = get_agent_card  # type: ignore[attr-defined]
+
+        # ── Preserve original class metadata ──────────────────────────────────
+        functools.update_wrapper(klass, klass, updated=[])
+
+        return klass
+
+    # Handle both @agent and @agent(...) call styles
+    if cls is not None:
+        # Called as @agent with no parentheses
+        return decorator(cls)
+
+    # Called as @agent(...) with arguments
+    return decorator
+
+
+# ── Public helper ─────────────────────────────────────────────────────────────
+
+def get_card(agent_cls: type) -> AgentCard:
+    """
+    Retrieve the AgentCard from a decorated agent class.
+
+    Args:
+        agent_cls: A class decorated with @agent.
+
+    Returns:
+        The AgentCard attached to the class.
+
+    Raises:
+        TypeError: If the class was not decorated with @agent.
+
+    Example:
+        card = get_card(ResearchAgent)
+        print(card.name)
+    """
+    card = getattr(agent_cls, _AGENT_CARD_ATTR, None)
+    if card is None:
+        raise TypeError(
+            f"'{agent_cls.__name__}' is not decorated with @agent. "
+            "Apply @agent before calling get_card()."
+        )
+    return cast(AgentCard, card)

nexus_a2a-0.1.0/nexus_a2a/models/agent.py

@@ -0,0 +1,192 @@
+"""
+nexus_a2a/models/agent.py
+
+Pydantic models that describe an AI agent's identity, capabilities,
+and skills — mirroring the A2A protocol's AgentCard specification.
+
+These models are the single source of truth for agent metadata
+across the entire package.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated, Any
+
+from pydantic import BaseModel, Field, HttpUrl, field_validator
+
+# ── Enums ─────────────────────────────────────────────────────────────────────
+
+class AuthScheme(str, Enum):
+    """Supported authentication schemes for agent-to-agent calls."""
+    NONE    = "none"
+    API_KEY = "api_key"
+    JWT     = "jwt"
+    OAUTH2  = "oauth2"
+
+
+class InputMode(str, Enum):
+    """MIME types an agent can accept as input."""
+    TEXT       = "text/plain"
+    JSON       = "application/json"
+    MULTIPART  = "multipart/form-data"
+
+
+class OutputMode(str, Enum):
+    """MIME types an agent can produce as output."""
+    TEXT       = "text/plain"
+    JSON       = "application/json"
+    MARKDOWN   = "text/markdown"
+
+
+# ── Sub-models ────────────────────────────────────────────────────────────────
+
+class AgentAuthentication(BaseModel):
+    """
+    Describes how a client must authenticate when calling this agent.
+
+    Example:
+        AgentAuthentication(scheme=AuthScheme.JWT, token_url="https://auth.example.com/token")
+    """
+    scheme:    AuthScheme = AuthScheme.NONE
+    token_url: HttpUrl | None = Field(
+        default=None,
+        description="URL to obtain a token — required for JWT and OAuth2 schemes.",
+    )
+    header_name: str | None = Field(
+        default=None,
+        description="Custom header name for API key auth. Defaults to 'X-API-Key'.",
+    )
+
+    model_config = {"use_enum_values": True}
+
+
+class AgentCapabilities(BaseModel):
+    """
+    Flags that describe what protocol features this agent supports.
+    The client uses these to decide how to interact with the agent.
+    """
+    streaming:          bool = Field(
+        default=False,
+        description="Agent supports Server-Sent Events for real-time task updates.",
+    )
+    push_notifications: bool = Field(
+        default=False,
+        description="Agent can POST task updates to a client-provided webhook URL.",
+    )
+    multi_turn:         bool = Field(
+        default=True,
+        description="Agent supports back-and-forth conversations within a single task.",
+    )
+
+
+class AgentSkill(BaseModel):
+    """
+    A single capability that an agent advertises.
+    Think of this as one entry in the agent's 'menu of services'.
+
+    Example:
+        AgentSkill(
+            id="web_search",
+            name="Web search",
+            description="Searches the web and returns summarised results.",
+            tags=["search", "web", "research"],
+            examples=["Search for latest AI papers", "Find Python docs for asyncio"],
+        )
+    """
+    id:          Annotated[str, Field(min_length=1, max_length=64)]
+    name:        Annotated[str, Field(min_length=1, max_length=128)]
+    description: Annotated[str, Field(min_length=1, max_length=1024)]
+    tags:        list[str] = Field(
+        default_factory=list,
+        description="Keywords that help agents discover this skill.",
+    )
+    examples:    list[str] = Field(
+        default_factory=list,
+        description="Sample inputs that demonstrate this skill.",
+    )
+
+    @field_validator("tags", "examples", mode="before")
+    @classmethod
+    def _no_empty_strings(cls, v: list[str]) -> list[str]:
+        """Strip whitespace and drop empty strings from lists."""
+        return [item.strip() for item in v if item.strip()]
+
+
+# ── Primary model ─────────────────────────────────────────────────────────────
+
+class AgentCard(BaseModel):
+    """
+    The complete identity document for an agent — exposed at the
+    well-known endpoint:  GET /.well-known/agent-card.json
+
+    This is what other agents read during discovery to learn:
+      - What the agent can do  (skills)
+      - How to reach it        (url)
+      - How to authenticate    (authentication)
+      - What formats it speaks (input_modes, output_modes)
+
+    Example:
+        AgentCard(
+            name="ResearchAgent",
+            description="Searches the web and summarises findings.",
+            version="1.0.0",
+            url="https://research-agent.example.com",
+            skills=[AgentSkill(id="search", name="Search", description="Web search")],
+        )
+    """
+
+    # Identity
+    name:        Annotated[str, Field(min_length=1, max_length=128)]
+    description: Annotated[str, Field(min_length=1, max_length=1024)]
+    version:     str = Field(
+        default="0.1.0",
+        description="Semantic version of this agent. Bump when skills change.",
+    )
+
+    # Network
+    url: HttpUrl = Field(
+        description="Base URL where this agent's A2A server is reachable.",
+    )
+
+    # Protocol
+    capabilities:  AgentCapabilities   = Field(default_factory=AgentCapabilities)
+    authentication: AgentAuthentication = Field(default_factory=AgentAuthentication)
+
+    # Skills
+    skills: list[AgentSkill] = Field(
+        default_factory=list,
+        description="List of capabilities this agent offers.",
+    )
+
+    # Communication formats
+    input_modes:  list[InputMode]  = Field(
+        default_factory=lambda: [InputMode.TEXT, InputMode.JSON],
+    )
+    output_modes: list[OutputMode] = Field(
+        default_factory=lambda: [OutputMode.TEXT, OutputMode.JSON],
+    )
+
+    model_config = {
+        "use_enum_values": True,
+        # Allows: AgentCard(**a2a_sdk_agent_card_dict) without extra fields
+        # causing an error — useful when parsing cards from external agents.
+        "extra": "ignore",
+    }
+
+    # ── Helpers ───────────────────────────────────────────────────────────────
+
+    def has_skill(self, skill_id: str) -> bool:
+        """Return True if this agent advertises the given skill id."""
+        return any(s.id == skill_id for s in self.skills)
+
+    def skill_ids(self) -> list[str]:
+        """Return a flat list of all advertised skill IDs."""
+        return [s.id for s in self.skills]
+
+    def to_well_known_dict(self) -> dict[str, Any] :
+        """
+        Serialise to the dict served at /.well-known/agent-card.json.
+        URLs are converted to plain strings so JSON serialisation works.
+        """
+        return self.model_dump(mode="json")