concursus 0.1.0__tar.gz

concursus-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tianpei Xie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

concursus-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: concursus
+Version: 0.1.0
+Summary: Compile a declarative DAG of subagents into an orchestrated team on AWS Bedrock AgentCore.
+Author-email: Tianpei Xie <unidoctor@gmail.com>
+Maintainer-email: Tianpei Xie <unidoctor@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/TianpeiLuke/concursus
+Project-URL: Repository, https://github.com/TianpeiLuke/concursus
+Project-URL: Issues, https://github.com/TianpeiLuke/concursus/issues
+Project-URL: Changelog, https://github.com/TianpeiLuke/concursus/blob/main/CHANGELOG.md
+Keywords: agentcore,bedrock,aws,multi-agent,agent-orchestration,llm-agents,dag,orchestration,supervisor,mcp,a2a
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: agentcore
+Requires-Dist: boto3>=1.34.0; extra == "agentcore"
+Requires-Dist: bedrock-agentcore; extra == "agentcore"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# Concursus
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+**Compile a declarative DAG of subagents into a deployed, orchestrated team on AWS Bedrock AgentCore.**
+
+Concursus (Latin *"a running-together / convergence"*) is [cursus](https://github.com/TianpeiLuke/cursus)'s agent-orchestration sibling. Where cursus compiles a pipeline DAG + configs into a SageMaker pipeline, Concursus compiles an **AgentDAG** + per-agent `.agent.yaml` manifests into (1) an AgentCore **provisioning plan** — one `CreateAgentRuntime` per agent — and (2) a **supervisor** that dispatches the agents in topological order, wires each agent's declared output into its dependents' input, and routes shared state through AgentCore **Memory**.
+
+It is the **coordinator AgentCore deliberately doesn't ship**: AgentCore gives you transport (A2A), tool discovery (Gateway), microVM isolation, identity, memory, and hosting — but no scheduler, dependency graph, or supervisor. You declare a DAG of agents; Concursus provisions them and runs them.
+
+> **Status: alpha.** This release ships the **declarative core** — the backend-agnostic `AgentDAG` and the `AgentManifest` (`.agent.yaml`) model, with validation. The AgentCore provisioning plan + supervisor (the `OrchestrationAssembler`) are on the [roadmap](#roadmap).
+
+---
+
+## Installation
+
+```bash
+pip install concursus                 # declarative core (pure Python)
+pip install "concursus[agentcore]"    # + the AWS Bedrock AgentCore runtime binding (roadmap)
+```
+
+Requires **Python 3.10+**.
+
+## Quick start
+
+Declare a team as an `AgentDAG` (nodes = agents, edges = data dependencies):
+
+```python
+from concursus import AgentDAG
+
+dag = AgentDAG()
+for agent in ["ingest", "summarize", "critique", "format"]:
+    dag.add_node(agent)
+dag.add_edge("ingest", "summarize")
+dag.add_edge("summarize", "critique")
+dag.add_edge("critique", "format")
+
+dag.topological_sort()   # ['ingest', 'summarize', 'critique', 'format']  <- dispatch order
+dag.validate()           # raises if the topology has a cycle
+```
+
+Describe each agent with an `.agent.yaml` manifest — its AgentCore binding + typed interface:
+
+```yaml
+# summarize.agent.yaml
+registry:
+  container_uri: 111122223333.dkr.ecr.us-east-1.amazonaws.com/summarize-agent:latest
+  role_arn: arn:aws:iam::111122223333:role/ConcursusAgentRuntimeRole
+  network_mode: PUBLIC       # or VPC
+  protocol: HTTP             # HTTP (/invocations) | MCP (/mcp) | A2A (/)
+  qualifier: DEFAULT
+  # ...or reuse an already-deployed agent:
+  # agent_runtime_arn: arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/summarize-xyz
+contract:
+  inputs:
+    document: {type: string}
+  outputs:                   # required — the dependency resolver's type gate
+    summary: {type: string}
+    key_points: {type: array, items: {type: string}}
+spec:
+  depends_on:
+    - {from: ingest.document, to: document}
+```
+
+```python
+from concursus import AgentManifest
+
+m = AgentManifest.from_yaml("summarize.agent.yaml").validate()
+m.protocol        # 'HTTP'
+m.output_schema   # {'summary': {...}, 'key_points': {...}}
+```
+
+Or from the CLI:
+
+```bash
+concursus info                        # overview
+concursus validate *.agent.yaml       # validate manifests
+concursus --version
+```
+
+## How it works (the compile target)
+
+Concursus compiles `AgentDAG + manifests` through `validate → resolve → provision → assemble`, mapping cursus concepts onto AgentCore primitives:
+
+| cursus | Concursus | AgentCore primitive |
+|---|---|---|
+| `PipelineDAG` | `AgentDAG` | dispatch order (topological) |
+| `.step.yaml` | `.agent.yaml` manifest | container image + `roleArn` + protocol |
+| `DependencyType` enum | output **JSON Schema** (mandatory) | the resolver's type gate |
+| `PropertyReference` (deferred) | `AgentRef` (eager JSONPath) | `InvokeAgentRuntime` response |
+| step registration | agent registration | `CreateAgentRuntime` → ARN + V1 + `DEFAULT` endpoint |
+| `PipelineAssembler` → `Pipeline` | `OrchestrationAssembler` → supervisor + plan | `BedrockAgentCoreApp` supervisor |
+| S3 artifact channels | shared run state | **AgentCore Memory** |
+
+The supervisor dispatches agents in topological order, invokes each with `InvokeAgentRuntime` under one `runtimeSessionId` (session affinity → warm microVMs), extracts each producer's output by JSONPath and injects it into its consumers, and persists outputs to Memory so state survives the ephemeral microVMs.
+
+## Roadmap
+
+- [x] Declarative core: `AgentDAG` + `AgentManifest` (`.agent.yaml`) + validation + CLI
+- [ ] Advisory dependency resolver over declared output JSON Schemas
+- [ ] `OrchestrationAssembler`: emit an AgentCore provisioning plan (`CreateAgentRuntime` per agent + IAM roles + endpoints)
+- [ ] The supervisor: topological dispatch over `InvokeAgentRuntime` with `AgentRef` wiring + Memory-backed state
+- [ ] Gateway/A2A node types; a data-driven catalog + recommender of team topologies
+
+## License
+
+MIT © Tianpei Xie

concursus-0.1.0/README.md

@@ -0,0 +1,108 @@
+# Concursus
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+**Compile a declarative DAG of subagents into a deployed, orchestrated team on AWS Bedrock AgentCore.**
+
+Concursus (Latin *"a running-together / convergence"*) is [cursus](https://github.com/TianpeiLuke/cursus)'s agent-orchestration sibling. Where cursus compiles a pipeline DAG + configs into a SageMaker pipeline, Concursus compiles an **AgentDAG** + per-agent `.agent.yaml` manifests into (1) an AgentCore **provisioning plan** — one `CreateAgentRuntime` per agent — and (2) a **supervisor** that dispatches the agents in topological order, wires each agent's declared output into its dependents' input, and routes shared state through AgentCore **Memory**.
+
+It is the **coordinator AgentCore deliberately doesn't ship**: AgentCore gives you transport (A2A), tool discovery (Gateway), microVM isolation, identity, memory, and hosting — but no scheduler, dependency graph, or supervisor. You declare a DAG of agents; Concursus provisions them and runs them.
+
+> **Status: alpha.** This release ships the **declarative core** — the backend-agnostic `AgentDAG` and the `AgentManifest` (`.agent.yaml`) model, with validation. The AgentCore provisioning plan + supervisor (the `OrchestrationAssembler`) are on the [roadmap](#roadmap).
+
+---
+
+## Installation
+
+```bash
+pip install concursus                 # declarative core (pure Python)
+pip install "concursus[agentcore]"    # + the AWS Bedrock AgentCore runtime binding (roadmap)
+```
+
+Requires **Python 3.10+**.
+
+## Quick start
+
+Declare a team as an `AgentDAG` (nodes = agents, edges = data dependencies):
+
+```python
+from concursus import AgentDAG
+
+dag = AgentDAG()
+for agent in ["ingest", "summarize", "critique", "format"]:
+    dag.add_node(agent)
+dag.add_edge("ingest", "summarize")
+dag.add_edge("summarize", "critique")
+dag.add_edge("critique", "format")
+
+dag.topological_sort()   # ['ingest', 'summarize', 'critique', 'format']  <- dispatch order
+dag.validate()           # raises if the topology has a cycle
+```
+
+Describe each agent with an `.agent.yaml` manifest — its AgentCore binding + typed interface:
+
+```yaml
+# summarize.agent.yaml
+registry:
+  container_uri: 111122223333.dkr.ecr.us-east-1.amazonaws.com/summarize-agent:latest
+  role_arn: arn:aws:iam::111122223333:role/ConcursusAgentRuntimeRole
+  network_mode: PUBLIC       # or VPC
+  protocol: HTTP             # HTTP (/invocations) | MCP (/mcp) | A2A (/)
+  qualifier: DEFAULT
+  # ...or reuse an already-deployed agent:
+  # agent_runtime_arn: arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/summarize-xyz
+contract:
+  inputs:
+    document: {type: string}
+  outputs:                   # required — the dependency resolver's type gate
+    summary: {type: string}
+    key_points: {type: array, items: {type: string}}
+spec:
+  depends_on:
+    - {from: ingest.document, to: document}
+```
+
+```python
+from concursus import AgentManifest
+
+m = AgentManifest.from_yaml("summarize.agent.yaml").validate()
+m.protocol        # 'HTTP'
+m.output_schema   # {'summary': {...}, 'key_points': {...}}
+```
+
+Or from the CLI:
+
+```bash
+concursus info                        # overview
+concursus validate *.agent.yaml       # validate manifests
+concursus --version
+```
+
+## How it works (the compile target)
+
+Concursus compiles `AgentDAG + manifests` through `validate → resolve → provision → assemble`, mapping cursus concepts onto AgentCore primitives:
+
+| cursus | Concursus | AgentCore primitive |
+|---|---|---|
+| `PipelineDAG` | `AgentDAG` | dispatch order (topological) |
+| `.step.yaml` | `.agent.yaml` manifest | container image + `roleArn` + protocol |
+| `DependencyType` enum | output **JSON Schema** (mandatory) | the resolver's type gate |
+| `PropertyReference` (deferred) | `AgentRef` (eager JSONPath) | `InvokeAgentRuntime` response |
+| step registration | agent registration | `CreateAgentRuntime` → ARN + V1 + `DEFAULT` endpoint |
+| `PipelineAssembler` → `Pipeline` | `OrchestrationAssembler` → supervisor + plan | `BedrockAgentCoreApp` supervisor |
+| S3 artifact channels | shared run state | **AgentCore Memory** |
+
+The supervisor dispatches agents in topological order, invokes each with `InvokeAgentRuntime` under one `runtimeSessionId` (session affinity → warm microVMs), extracts each producer's output by JSONPath and injects it into its consumers, and persists outputs to Memory so state survives the ephemeral microVMs.
+
+## Roadmap
+
+- [x] Declarative core: `AgentDAG` + `AgentManifest` (`.agent.yaml`) + validation + CLI
+- [ ] Advisory dependency resolver over declared output JSON Schemas
+- [ ] `OrchestrationAssembler`: emit an AgentCore provisioning plan (`CreateAgentRuntime` per agent + IAM roles + endpoints)
+- [ ] The supervisor: topological dispatch over `InvokeAgentRuntime` with `AgentRef` wiring + Memory-backed state
+- [ ] Gateway/A2A node types; a data-driven catalog + recommender of team topologies
+
+## License
+
+MIT © Tianpei Xie

concursus-0.1.0/VERSION

@@ -0,0 +1 @@
+0.1.0

concursus-0.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "concursus"
+dynamic = ["version"]
+description = "Compile a declarative DAG of subagents into an orchestrated team on AWS Bedrock AgentCore."
+readme = "README.md"
+license = "MIT"
+authors = [
+    {name = "Tianpei Xie", email = "unidoctor@gmail.com"}
+]
+maintainers = [
+    {name = "Tianpei Xie", email = "unidoctor@gmail.com"}
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Distributed Computing",
+    "Typing :: Typed",
+]
+keywords = [
+    "agentcore",
+    "bedrock",
+    "aws",
+    "multi-agent",
+    "agent-orchestration",
+    "llm-agents",
+    "dag",
+    "orchestration",
+    "supervisor",
+    "mcp",
+    "a2a",
+]
+requires-python = ">=3.10"
+
+# Core is pure-Python: the declarative AgentDAG + .agent.yaml manifest model.
+dependencies = [
+    "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+# The AWS Bedrock AgentCore runtime binding (provisioning + invocation). Kept optional so
+# the declarative core installs without the AWS stack.
+agentcore = [
+    "boto3>=1.34.0",
+    "bedrock-agentcore",
+]
+dev = [
+    "pytest>=7.0.0",
+    "build>=1.0.0",
+    "twine>=5.0.0",
+    "black>=23.0.0",
+    "mypy>=1.0.0",
+]
+
+[project.scripts]
+concursus = "concursus.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/TianpeiLuke/concursus"
+Repository = "https://github.com/TianpeiLuke/concursus"
+Issues = "https://github.com/TianpeiLuke/concursus/issues"
+Changelog = "https://github.com/TianpeiLuke/concursus/blob/main/CHANGELOG.md"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.dynamic]
+version = {file = "VERSION"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["concursus*"]
+
+[tool.setuptools.package-data]
+"concursus" = ["py.typed"]
+
+[tool.black]
+line-length = 95
+target-version = ["py310", "py311", "py312"]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra -q"
+testpaths = ["tests"]

concursus-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

concursus-0.1.0/src/concursus/__init__.py

@@ -0,0 +1,61 @@
+"""Concursus — compile a DAG of subagents into an orchestrated team on AWS Bedrock AgentCore.
+
+Where **cursus** compiles a pipeline DAG + configs into a SageMaker pipeline, **Concursus**
+(Latin *"a running-together / convergence"*) compiles an ``AgentDAG`` + per-agent
+``.agent.yaml`` manifests into (1) an AgentCore provisioning plan — one ``CreateAgentRuntime``
+per agent — and (2) a supervisor that dispatches the agents in topological order, wires each
+agent's declared output into its dependents' input, and routes shared state through AgentCore
+Memory. It is the coordinator AgentCore deliberately does not ship.
+
+Status: early. This release provides the declarative core — the backend-agnostic
+:class:`~concursus.dag.AgentDAG` and the :class:`~concursus.manifest.AgentManifest`
+(``.agent.yaml``) model. The AgentCore provisioning plan + supervisor (the
+``OrchestrationAssembler``) are the roadmap.
+
+Basic usage:
+    >>> from concursus import AgentDAG
+    >>> dag = AgentDAG()
+    >>> for n in ["ingest", "summarize", "critique", "format"]:
+    ...     dag.add_node(n)
+    >>> dag.add_edge("ingest", "summarize").add_edge("summarize", "critique")
+    >>> dag.add_edge("critique", "format").topological_sort()
+    ['ingest', 'summarize', 'critique', 'format']
+"""
+
+from __future__ import annotations
+
+
+def _resolve_version() -> str:
+    """Resolve the version: a VERSION file (dev source of truth) wins over installed metadata."""
+    from pathlib import Path
+
+    version = "0.0.0"
+    try:
+        from importlib.metadata import version as _dist_version
+
+        version = _dist_version("concursus")
+    except Exception:  # pragma: no cover - not installed / odd checkout
+        pass
+    _v_file = Path(__file__).resolve().parent.parent.parent / "VERSION"
+    if _v_file.exists():
+        try:
+            text = _v_file.read_text().strip()
+            if text:
+                version = text
+        except OSError:
+            pass
+    return version
+
+
+__version__ = _resolve_version()
+
+from .dag import AgentDAG, DAGError
+from .manifest import AgentManifest, ManifestError
+
+__all__ = [
+    "AgentDAG",
+    "DAGError",
+    "AgentManifest",
+    "ManifestError",
+    "__version__",
+]

concursus-0.1.0/src/concursus/cli.py

@@ -0,0 +1,73 @@
+"""The ``concursus`` command-line entry point.
+
+Minimal for now: report the version, print an overview, and validate ``.agent.yaml``
+manifests. The ``plan`` / ``deploy`` / ``run`` verbs (compile an AgentDAG into an AgentCore
+provisioning plan + supervisor) are the roadmap.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+from . import __version__
+
+
+def _cmd_info(_args: argparse.Namespace) -> int:
+    print(
+        "concursus {v}\n\n"
+        "Compile a declarative DAG of subagents into an orchestrated team on AWS Bedrock\n"
+        "AgentCore. You declare an AgentDAG (nodes = agents, edges = data dependencies) and\n"
+        "one .agent.yaml manifest per agent; Concursus provisions each agent with\n"
+        "CreateAgentRuntime and runs them with a topological supervisor over InvokeAgentRuntime,\n"
+        "wiring outputs to inputs and routing shared state through AgentCore Memory.\n\n"
+        "Status: early — this release ships the declarative core (AgentDAG + AgentManifest).\n"
+        "Roadmap: the OrchestrationAssembler (provisioning plan + supervisor).".format(
+            v=__version__
+        )
+    )
+    return 0
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    from .manifest import AgentManifest, ManifestError
+
+    rc = 0
+    for path in args.manifests:
+        try:
+            m = AgentManifest.from_yaml(path).validate()
+            print(f"OK    {path}  (agent '{m.name}', protocol {m.protocol})")
+        except (ManifestError, OSError, ValueError) as exc:
+            print(f"FAIL  {path}  -> {exc}", file=sys.stderr)
+            rc = 1
+    return rc
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="concursus",
+        description="Compile a DAG of subagents into an orchestrated team on AWS Bedrock AgentCore.",
+    )
+    p.add_argument("--version", action="version", version=f"concursus {__version__}")
+    sub = p.add_subparsers(dest="command")
+
+    sub.add_parser("info", help="Print an overview of Concursus.").set_defaults(func=_cmd_info)
+
+    v = sub.add_parser("validate", help="Validate one or more .agent.yaml manifests.")
+    v.add_argument("manifests", nargs="+", help="Path(s) to .agent.yaml file(s).")
+    v.set_defaults(func=_cmd_validate)
+
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "command", None):
+        return _cmd_info(args)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

concursus-0.1.0/src/concursus/dag.py

@@ -0,0 +1,119 @@
+"""The AgentDAG — a pure, backend-agnostic directed acyclic graph of agents/tasks.
+
+Nodes are agent ids (strings); edges are data dependencies (``a -> b`` means *b depends
+on a*). The DAG is the topology Concursus compiles into a dispatch order: a topological
+sort gives a valid run order, independent nodes can run concurrently, and a join waits for
+all inbound edges. This layer carries no AWS/AgentCore coupling — it is the reused core of
+the design (the analog of cursus's ``PipelineDAG``).
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Iterable, List, Set
+
+
+class DAGError(ValueError):
+    """Raised on an invalid DAG (unknown node, or a cycle)."""
+
+
+class AgentDAG:
+    """A directed acyclic graph whose nodes are agent/task ids.
+
+    Example:
+        >>> dag = AgentDAG()
+        >>> for n in ["ingest", "summarize", "critique", "format"]:
+        ...     dag.add_node(n)
+        >>> dag.add_edge("ingest", "summarize")
+        >>> dag.add_edge("summarize", "critique")
+        >>> dag.add_edge("critique", "format")
+        >>> dag.topological_sort()
+        ['ingest', 'summarize', 'critique', 'format']
+    """
+
+    def __init__(self) -> None:
+        self._nodes: Set[str] = set()
+        self._edges: List[tuple] = []  # (from_node, to_node)
+
+    # -- construction -------------------------------------------------------
+    def add_node(self, name: str) -> "AgentDAG":
+        if not isinstance(name, str) or not name.strip():
+            raise DAGError("node name must be a non-empty string")
+        self._nodes.add(name)
+        return self
+
+    def add_edge(self, from_node: str, to_node: str) -> "AgentDAG":
+        """Add a data dependency ``from_node -> to_node`` (to_node depends on from_node)."""
+        for n in (from_node, to_node):
+            if n not in self._nodes:
+                raise DAGError(f"unknown node: {n!r} (add_node first)")
+        if from_node == to_node:
+            raise DAGError(f"self-loop not allowed: {from_node!r}")
+        if (from_node, to_node) not in self._edges:
+            self._edges.append((from_node, to_node))
+        return self
+
+    # -- inspection ---------------------------------------------------------
+    @property
+    def nodes(self) -> List[str]:
+        return sorted(self._nodes)
+
+    @property
+    def edges(self) -> List[tuple]:
+        return list(self._edges)
+
+    def get_dependencies(self, node: str) -> List[str]:
+        """Direct upstream producers of ``node``."""
+        return sorted(f for f, t in self._edges if t == node)
+
+    def get_dependents(self, node: str) -> List[str]:
+        """Direct downstream consumers of ``node``."""
+        return sorted(t for f, t in self._edges if f == node)
+
+    def sources(self) -> List[str]:
+        """Nodes with no dependencies (entry points)."""
+        return sorted(n for n in self._nodes if not self.get_dependencies(n))
+
+    def sinks(self) -> List[str]:
+        """Nodes with no dependents (terminals)."""
+        return sorted(n for n in self._nodes if not self.get_dependents(n))
+
+    # -- ordering -----------------------------------------------------------
+    def topological_sort(self) -> List[str]:
+        """Return a valid dispatch order (Kahn's algorithm). Raises on a cycle."""
+        indeg: Dict[str, int] = {n: 0 for n in self._nodes}
+        for _, t in self._edges:
+            indeg[t] += 1
+        ready = sorted(n for n, d in indeg.items() if d == 0)
+        order: List[str] = []
+        while ready:
+            n = ready.pop(0)
+            order.append(n)
+            for t in self.get_dependents(n):
+                indeg[t] -= 1
+                if indeg[t] == 0:
+                    ready.append(t)
+            ready.sort()
+        if len(order) != len(self._nodes):
+            raise DAGError("DAG contains a cycle; agent topologies must be acyclic")
+        return order
+
+    def validate(self) -> "AgentDAG":
+        """Assert the graph is a valid DAG (no cycles); returns self."""
+        self.topological_sort()
+        return self
+
+    # -- serialization ------------------------------------------------------
+    def to_dict(self) -> dict:
+        return {"nodes": self.nodes, "edges": [list(e) for e in self._edges]}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "AgentDAG":
+        dag = cls()
+        for n in data.get("nodes", []):
+            dag.add_node(n)
+        for e in data.get("edges", []):
+            dag.add_edge(e[0], e[1])
+        return dag
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"AgentDAG(nodes={len(self._nodes)}, edges={len(self._edges)})"

concursus-0.1.0/src/concursus/manifest.py

@@ -0,0 +1,110 @@
+"""The ``.agent.yaml`` manifest model — a single agent's interface + AgentCore binding.
+
+An agent manifest declares three things:
+
+- ``registry`` — how the agent is hosted on AgentCore (a container image to provision, or an
+  existing ``agent_runtime_arn`` to reuse), plus its protocol and endpoint qualifier.
+- ``contract`` — the agent's typed interface: the input fields Concursus injects into the
+  invoke payload, and the **output JSON Schema** (required — it is the dependency resolver's
+  type gate).
+- ``spec`` — optional author-declared edges (``depends_on``) wiring upstream outputs to this
+  agent's inputs.
+
+This is the declarative core Concursus compiles down to ``CreateAgentRuntime`` /
+``InvokeAgentRuntime`` calls; the runtime/assembler that consumes it is on the roadmap.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+
+class ManifestError(ValueError):
+    """Raised on an invalid agent manifest."""
+
+
+@dataclass
+class AgentManifest:
+    """Parsed ``<name>.agent.yaml``.
+
+    Attributes:
+        name: The agent/node id (unique within an :class:`~concursus.dag.AgentDAG`).
+        registry: Hosting binding — e.g. ``container_uri`` + ``role_arn`` + ``network_mode``
+            + ``protocol`` (``HTTP`` | ``MCP`` | ``A2A``) + ``qualifier``, or
+            ``agent_runtime_arn`` to reuse an already-deployed runtime.
+        contract: ``{"inputs": {...}, "outputs": {<json-schema>}}``.
+        spec: Optional ``{"depends_on": [{"from": "producer.field", "to": "input"}]}``.
+    """
+
+    name: str
+    registry: Dict[str, Any] = field(default_factory=dict)
+    contract: Dict[str, Any] = field(default_factory=dict)
+    spec: Dict[str, Any] = field(default_factory=dict)
+
+    # -- accessors ----------------------------------------------------------
+    @property
+    def protocol(self) -> str:
+        return str(self.registry.get("protocol", "HTTP")).upper()
+
+    @property
+    def inputs(self) -> Dict[str, Any]:
+        return dict(self.contract.get("inputs", {}))
+
+    @property
+    def output_schema(self) -> Dict[str, Any]:
+        return dict(self.contract.get("outputs", {}))
+
+    @property
+    def depends_on(self) -> List[Dict[str, str]]:
+        return list(self.spec.get("depends_on", []))
+
+    # -- validation ---------------------------------------------------------
+    def validate(self) -> "AgentManifest":
+        """Enforce the manifest contract; returns self.
+
+        Rules: a name is required; the registry must name either a ``container_uri`` (to
+        provision) or an ``agent_runtime_arn`` (to reuse); and an **output schema is
+        mandatory** — it is what makes dependency resolution meaningful for agents.
+        """
+        if not self.name or not str(self.name).strip():
+            raise ManifestError("manifest requires a non-empty 'name'")
+        reg = self.registry
+        if not (reg.get("container_uri") or reg.get("agent_runtime_arn")):
+            raise ManifestError(
+                f"{self.name}: registry must set 'container_uri' (to provision) or "
+                "'agent_runtime_arn' (to reuse an existing AgentCore Runtime)"
+            )
+        if self.protocol not in ("HTTP", "MCP", "A2A"):
+            raise ManifestError(
+                f"{self.name}: protocol must be HTTP, MCP, or A2A (got {self.protocol!r})"
+            )
+        if not self.output_schema:
+            raise ManifestError(
+                f"{self.name}: contract.outputs (a JSON Schema) is required — it is the "
+                "dependency resolver's type gate"
+            )
+        return self
+
+    # -- construction -------------------------------------------------------
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "AgentManifest":
+        return cls(
+            name=data.get("name", ""),
+            registry=dict(data.get("registry", {})),
+            contract=dict(data.get("contract", {})),
+            spec=dict(data.get("spec", {})),
+        )
+
+    @classmethod
+    def from_yaml(cls, path: str) -> "AgentManifest":
+        """Load a ``.agent.yaml`` file. The name defaults to the file stem if unset."""
+        import os
+
+        import yaml  # lazy: only needed when actually loading a manifest file
+
+        with open(path, "r", encoding="utf-8") as fh:
+            data = yaml.safe_load(fh) or {}
+        if not data.get("name"):
+            data["name"] = os.path.basename(path).split(".", 1)[0]
+        return cls.from_dict(data)

concursus-0.1.0/src/concursus.egg-info/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: concursus
+Version: 0.1.0
+Summary: Compile a declarative DAG of subagents into an orchestrated team on AWS Bedrock AgentCore.
+Author-email: Tianpei Xie <unidoctor@gmail.com>
+Maintainer-email: Tianpei Xie <unidoctor@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/TianpeiLuke/concursus
+Project-URL: Repository, https://github.com/TianpeiLuke/concursus
+Project-URL: Issues, https://github.com/TianpeiLuke/concursus/issues
+Project-URL: Changelog, https://github.com/TianpeiLuke/concursus/blob/main/CHANGELOG.md
+Keywords: agentcore,bedrock,aws,multi-agent,agent-orchestration,llm-agents,dag,orchestration,supervisor,mcp,a2a
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: agentcore
+Requires-Dist: boto3>=1.34.0; extra == "agentcore"
+Requires-Dist: bedrock-agentcore; extra == "agentcore"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# Concursus
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+**Compile a declarative DAG of subagents into a deployed, orchestrated team on AWS Bedrock AgentCore.**
+
+Concursus (Latin *"a running-together / convergence"*) is [cursus](https://github.com/TianpeiLuke/cursus)'s agent-orchestration sibling. Where cursus compiles a pipeline DAG + configs into a SageMaker pipeline, Concursus compiles an **AgentDAG** + per-agent `.agent.yaml` manifests into (1) an AgentCore **provisioning plan** — one `CreateAgentRuntime` per agent — and (2) a **supervisor** that dispatches the agents in topological order, wires each agent's declared output into its dependents' input, and routes shared state through AgentCore **Memory**.
+
+It is the **coordinator AgentCore deliberately doesn't ship**: AgentCore gives you transport (A2A), tool discovery (Gateway), microVM isolation, identity, memory, and hosting — but no scheduler, dependency graph, or supervisor. You declare a DAG of agents; Concursus provisions them and runs them.
+
+> **Status: alpha.** This release ships the **declarative core** — the backend-agnostic `AgentDAG` and the `AgentManifest` (`.agent.yaml`) model, with validation. The AgentCore provisioning plan + supervisor (the `OrchestrationAssembler`) are on the [roadmap](#roadmap).
+
+---
+
+## Installation
+
+```bash
+pip install concursus                 # declarative core (pure Python)
+pip install "concursus[agentcore]"    # + the AWS Bedrock AgentCore runtime binding (roadmap)
+```
+
+Requires **Python 3.10+**.
+
+## Quick start
+
+Declare a team as an `AgentDAG` (nodes = agents, edges = data dependencies):
+
+```python
+from concursus import AgentDAG
+
+dag = AgentDAG()
+for agent in ["ingest", "summarize", "critique", "format"]:
+    dag.add_node(agent)
+dag.add_edge("ingest", "summarize")
+dag.add_edge("summarize", "critique")
+dag.add_edge("critique", "format")
+
+dag.topological_sort()   # ['ingest', 'summarize', 'critique', 'format']  <- dispatch order
+dag.validate()           # raises if the topology has a cycle
+```
+
+Describe each agent with an `.agent.yaml` manifest — its AgentCore binding + typed interface:
+
+```yaml
+# summarize.agent.yaml
+registry:
+  container_uri: 111122223333.dkr.ecr.us-east-1.amazonaws.com/summarize-agent:latest
+  role_arn: arn:aws:iam::111122223333:role/ConcursusAgentRuntimeRole
+  network_mode: PUBLIC       # or VPC
+  protocol: HTTP             # HTTP (/invocations) | MCP (/mcp) | A2A (/)
+  qualifier: DEFAULT
+  # ...or reuse an already-deployed agent:
+  # agent_runtime_arn: arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/summarize-xyz
+contract:
+  inputs:
+    document: {type: string}
+  outputs:                   # required — the dependency resolver's type gate
+    summary: {type: string}
+    key_points: {type: array, items: {type: string}}
+spec:
+  depends_on:
+    - {from: ingest.document, to: document}
+```
+
+```python
+from concursus import AgentManifest
+
+m = AgentManifest.from_yaml("summarize.agent.yaml").validate()
+m.protocol        # 'HTTP'
+m.output_schema   # {'summary': {...}, 'key_points': {...}}
+```
+
+Or from the CLI:
+
+```bash
+concursus info                        # overview
+concursus validate *.agent.yaml       # validate manifests
+concursus --version
+```
+
+## How it works (the compile target)
+
+Concursus compiles `AgentDAG + manifests` through `validate → resolve → provision → assemble`, mapping cursus concepts onto AgentCore primitives:
+
+| cursus | Concursus | AgentCore primitive |
+|---|---|---|
+| `PipelineDAG` | `AgentDAG` | dispatch order (topological) |
+| `.step.yaml` | `.agent.yaml` manifest | container image + `roleArn` + protocol |
+| `DependencyType` enum | output **JSON Schema** (mandatory) | the resolver's type gate |
+| `PropertyReference` (deferred) | `AgentRef` (eager JSONPath) | `InvokeAgentRuntime` response |
+| step registration | agent registration | `CreateAgentRuntime` → ARN + V1 + `DEFAULT` endpoint |
+| `PipelineAssembler` → `Pipeline` | `OrchestrationAssembler` → supervisor + plan | `BedrockAgentCoreApp` supervisor |
+| S3 artifact channels | shared run state | **AgentCore Memory** |
+
+The supervisor dispatches agents in topological order, invokes each with `InvokeAgentRuntime` under one `runtimeSessionId` (session affinity → warm microVMs), extracts each producer's output by JSONPath and injects it into its consumers, and persists outputs to Memory so state survives the ephemeral microVMs.
+
+## Roadmap
+
+- [x] Declarative core: `AgentDAG` + `AgentManifest` (`.agent.yaml`) + validation + CLI
+- [ ] Advisory dependency resolver over declared output JSON Schemas
+- [ ] `OrchestrationAssembler`: emit an AgentCore provisioning plan (`CreateAgentRuntime` per agent + IAM roles + endpoints)
+- [ ] The supervisor: topological dispatch over `InvokeAgentRuntime` with `AgentRef` wiring + Memory-backed state
+- [ ] Gateway/A2A node types; a data-driven catalog + recommender of team topologies
+
+## License
+
+MIT © Tianpei Xie

concursus-0.1.0/src/concursus.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+VERSION
+pyproject.toml
+src/concursus/__init__.py
+src/concursus/cli.py
+src/concursus/dag.py
+src/concursus/manifest.py
+src/concursus/py.typed
+src/concursus.egg-info/PKG-INFO
+src/concursus.egg-info/SOURCES.txt
+src/concursus.egg-info/dependency_links.txt
+src/concursus.egg-info/entry_points.txt
+src/concursus.egg-info/requires.txt
+src/concursus.egg-info/top_level.txt
+tests/test_core.py

concursus-0.1.0/src/concursus.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

concursus-0.1.0/src/concursus.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+concursus = concursus.cli:main

concursus-0.1.0/src/concursus.egg-info/requires.txt

@@ -0,0 +1,12 @@
+PyYAML>=6.0
+
+[agentcore]
+boto3>=1.34.0
+bedrock-agentcore
+
+[dev]
+pytest>=7.0.0
+build>=1.0.0
+twine>=5.0.0
+black>=23.0.0
+mypy>=1.0.0

concursus-0.1.0/src/concursus.egg-info/top_level.txt

@@ -0,0 +1 @@
+concursus

concursus-0.1.0/tests/test_core.py

@@ -0,0 +1,71 @@
+"""Smoke tests for the Concursus declarative core."""
+
+import pytest
+
+from concursus import AgentDAG, AgentManifest, DAGError, ManifestError, __version__
+
+
+def test_version_resolves():
+    assert __version__ and __version__ != "0.0.0"
+
+
+def test_dag_topological_order():
+    dag = AgentDAG()
+    for n in ["ingest", "summarize", "critique", "format"]:
+        dag.add_node(n)
+    dag.add_edge("ingest", "summarize")
+    dag.add_edge("summarize", "critique")
+    dag.add_edge("critique", "format")
+    assert dag.topological_sort() == ["ingest", "summarize", "critique", "format"]
+    assert dag.sources() == ["ingest"]
+    assert dag.sinks() == ["format"]
+    assert dag.get_dependencies("critique") == ["summarize"]
+
+
+def test_dag_detects_cycle():
+    dag = AgentDAG()
+    for n in ["a", "b"]:
+        dag.add_node(n)
+    dag.add_edge("a", "b")
+    dag.add_edge("b", "a")
+    with pytest.raises(DAGError):
+        dag.topological_sort()
+
+
+def test_dag_round_trips():
+    dag = AgentDAG.from_dict({"nodes": ["a", "b"], "edges": [["a", "b"]]})
+    assert dag.to_dict() == {"nodes": ["a", "b"], "edges": [["a", "b"]]}
+
+
+def test_dag_rejects_unknown_edge_node():
+    dag = AgentDAG().add_node("a")
+    with pytest.raises(DAGError):
+        dag.add_edge("a", "missing")
+
+
+def test_manifest_validates():
+    m = AgentManifest.from_dict(
+        {
+            "name": "summarize",
+            "registry": {"container_uri": "acct.dkr.ecr.us-east-1.amazonaws.com/x:latest",
+                         "protocol": "HTTP"},
+            "contract": {"inputs": {"document": {"type": "string"}},
+                         "outputs": {"summary": {"type": "string"}}},
+        }
+    ).validate()
+    assert m.protocol == "HTTP"
+    assert "summary" in m.output_schema
+
+
+def test_manifest_requires_output_schema():
+    with pytest.raises(ManifestError):
+        AgentManifest.from_dict(
+            {"name": "x", "registry": {"container_uri": "y"}, "contract": {}}
+        ).validate()
+
+
+def test_manifest_requires_hosting_binding():
+    with pytest.raises(ManifestError):
+        AgentManifest.from_dict(
+            {"name": "x", "contract": {"outputs": {"o": {"type": "string"}}}}
+        ).validate()