orcha-sdk 0.1.1__tar.gz

orcha_sdk-0.1.1/.gitignore

@@ -0,0 +1,130 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environments
+.env.*
+.env
+.venv/
+env/
+venv/
+ENV/
+
+# uv
+.uv/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.tox/
+*.cover
+*.log
+
+# Prisma
+node_modules/
+common/database/src/generated_client/
+*.db
+*.db-journal
+
+# gRPC Generated
+common/proto/src/*_pb2.py
+common/proto/src/*_pb2_grpc.py
+common/proto/src/*_pb2.pyi
+
+# Logs
+*.log
+logs/
+dist/
+
+# Database
+*.sqlite
+*.sqlite3
+
+# Environment
+.env.local
+.env.*.local
+.env.production
+.env.*
+!.env.example
+!.env.sandbox.example
+
+# Docker
+.dockerignore
+
+# SSH keys / certificates / credentials (never commit these)
+*.pem
+*.key
+*.p12
+*.pfx
+*_SERV_ACC*.json
+*service-account*.json
+*service_account*.json
+GOOGLE_SERV_ACC*.json
+*credentials*.json
+*-credentials.json
+gcp-*.json
+startup.log
+
+# OS
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.temp
+*.bak
+.ruff_cache
+.logs
+ctx/
+
+# Local-only docs — internal moat/strategy/pricing notes, PDFs, recordings.
+# Populated by scripts/mirror-local-docs.sh; never meant to leave this machine.
+docs-local/
+
+# DAN / vision / network material — kept locally, not in the public repo
+INCEPTION.md
+VISION.md
+docs/dev_docs/dan/
+docs/dev_docs/EmergeOS-DAN.pdf
+node/src/emerge_node/gossip.py
+node/src/emerge_node/cli.py
+node/tests/test_gossip_spike.py
+.cdv-runs/
+.wrangler/
+kimi files/
+kimi-export-*.md
+.superpowers/
+
+# Editor/harness rule files and local font cache — machine-local, never the repo's
+.cursor/
+.fonts/
+
+# Landing site lives in solvent-labs-org/orcha-landing; local checkout kept here for convenience.
+deploy/landing-site/

orcha_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.5
+Name: orcha-sdk
+Version: 0.1.1
+Summary: Orcha agent SDK + CLI — register an agent in three lines.
+Project-URL: Homepage, https://github.com/solvent-labs-org/metaorcha
+Project-URL: Repository, https://github.com/solvent-labs-org/metaorcha
+Project-URL: Issues, https://github.com/solvent-labs-org/metaorcha/issues
+Author: Orcha
+License: MIT
+Keywords: a2a,ai-agents,emerge,mcp,orcha,orchestration
+Classifier: Development Status :: 4 - Beta
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# orcha-sdk
+
+The developer SDK + `emerge` CLI for [Orcha](https://github.com/solvent-labs-org/metaorcha) —
+an orchestration runtime that plans, routes, and executes one goal across agents
+speaking MCP, A2A, and COMPUTER_USE (ACP is accepted as an A2A-routed alias).
+
+Register an agent in three lines:
+
+```python
+import emerge
+
+@emerge.agent(name="My Agent", description="What I do")
+def handle(task: str) -> str:
+    return f"handled: {task}"
+```
+
+Then serve it:
+
+```bash
+orcha-sdk run          # serve locally + register against the local registry
+```
+
+## Install
+
+No clone, no venv setup — just run it:
+
+```bash
+uvx orcha-sdk init my-agent
+```
+
+Or install it into a project:
+
+```bash
+pip install orcha-sdk
+```
+
+(Import name is `emerge`; distribution name is `orcha-sdk`.)
+
+## CLI
+
+| Command | What it does |
+|---|---|
+| `orcha-sdk init "My Agent"` | scaffold a new agent from a template |
+| `orcha-sdk run [module]` | serve decorated agents locally + register them against `http://localhost:8000` |
+| `orcha-sdk publish [module] --registry <url>` | register against a remote registry |
+
+`orcha-sdk run --no-register` serves without registering. Set `ORCHA_REGISTRY_URL`
+and `ORCHA_PAT` to point at and authenticate against a non-local registry.
+
+## How it works
+
+The decorator records your handler and declared skills. `orcha-sdk run` serves an
+A2A-compatible HTTP endpoint (`/health`, `/.well-known/agent.json`, JSON-RPC
+`message/send` / `tasks/get`) using only the standard library, and uploads a
+generated `emerge.yaml` to the registry. The runtime's planner can then discover
+and orchestrate your agent alongside agents that speak other protocols.
+
+Apache 2.0 runtime, MIT SDK. See the [main repo](https://github.com/solvent-labs-org/metaorcha).

orcha_sdk-0.1.1/README.md

@@ -0,0 +1,58 @@
+# orcha-sdk
+
+The developer SDK + `emerge` CLI for [Orcha](https://github.com/solvent-labs-org/metaorcha) —
+an orchestration runtime that plans, routes, and executes one goal across agents
+speaking MCP, A2A, and COMPUTER_USE (ACP is accepted as an A2A-routed alias).
+
+Register an agent in three lines:
+
+```python
+import emerge
+
+@emerge.agent(name="My Agent", description="What I do")
+def handle(task: str) -> str:
+    return f"handled: {task}"
+```
+
+Then serve it:
+
+```bash
+orcha-sdk run          # serve locally + register against the local registry
+```
+
+## Install
+
+No clone, no venv setup — just run it:
+
+```bash
+uvx orcha-sdk init my-agent
+```
+
+Or install it into a project:
+
+```bash
+pip install orcha-sdk
+```
+
+(Import name is `emerge`; distribution name is `orcha-sdk`.)
+
+## CLI
+
+| Command | What it does |
+|---|---|
+| `orcha-sdk init "My Agent"` | scaffold a new agent from a template |
+| `orcha-sdk run [module]` | serve decorated agents locally + register them against `http://localhost:8000` |
+| `orcha-sdk publish [module] --registry <url>` | register against a remote registry |
+
+`orcha-sdk run --no-register` serves without registering. Set `ORCHA_REGISTRY_URL`
+and `ORCHA_PAT` to point at and authenticate against a non-local registry.
+
+## How it works
+
+The decorator records your handler and declared skills. `orcha-sdk run` serves an
+A2A-compatible HTTP endpoint (`/health`, `/.well-known/agent.json`, JSON-RPC
+`message/send` / `tasks/get`) using only the standard library, and uploads a
+generated `emerge.yaml` to the registry. The runtime's planner can then discover
+and orchestrate your agent alongside agents that speak other protocols.
+
+Apache 2.0 runtime, MIT SDK. See the [main repo](https://github.com/solvent-labs-org/metaorcha).

orcha_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "orcha-sdk"
+version = "0.1.1"
+description = "Orcha agent SDK + CLI — register an agent in three lines."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Orcha" }]
+keywords = ["ai-agents", "mcp", "a2a", "orchestration", "orcha", "emerge"]
+dependencies = [
+    "pyyaml>=6.0",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "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",
+]
+
+[project.urls]
+Homepage = "https://github.com/solvent-labs-org/metaorcha"
+Repository = "https://github.com/solvent-labs-org/metaorcha"
+Issues = "https://github.com/solvent-labs-org/metaorcha/issues"
+
+[project.scripts]
+# `uvx <name>` resolves the *distribution* name, so the primary console script
+# must match it for `uvx orcha-sdk init` to work. `emerge` stays as an alias.
+orcha-sdk = "emerge.cli:main"
+emerge = "emerge.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/emerge"]

orcha_sdk-0.1.1/src/emerge/__init__.py

@@ -0,0 +1,60 @@
+"""Orcha agent SDK — register an agent in three lines.
+
+    import emerge
+
+    @emerge.agent(name="My Agent", description="What I do")
+    def handle(task: str) -> str:
+        return f"handled: {task}"
+
+    if __name__ == "__main__":
+        emerge.run()
+
+Or use the CLI: ``emerge run`` / ``emerge publish``.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .manifest import build_manifest, manifest_yaml
+from .sdk import AgentSpec, Skill, agent, registered_agents
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "agent",
+    "Skill",
+    "AgentSpec",
+    "registered_agents",
+    "build_manifest",
+    "manifest_yaml",
+    "run",
+    "__version__",
+]
+
+
+def run() -> int:
+    """Serve every decorated agent in this process (convenience for ``__main__``).
+
+    Agents are already registered via import, so this just serves them — it does
+    not register against a registry. Use the ``emerge run`` CLI for registration.
+    """
+    from .server import serve_agent
+
+    agents = registered_agents()
+    if not agents:
+        print(
+            "emerge.run(): no @emerge.agent registered in this module.", file=sys.stderr
+        )
+        return 1
+    for spec in agents[:-1]:
+        serve_agent(spec, block=False)
+        print(f"✓ Serving {spec.name} on http://localhost:{spec.port}  ({spec.did})")
+    last = agents[-1]
+    print(f"✓ Serving {last.name} on http://localhost:{last.port}  ({last.did})")
+    print("Press Ctrl+C to stop.")
+    try:
+        serve_agent(last, block=True)
+    except KeyboardInterrupt:
+        print("\nStopped.")
+    return 0

orcha_sdk-0.1.1/src/emerge/cli.py

@@ -0,0 +1,311 @@
+"""Orcha agent CLI — the launch-scope developer surface.
+
+Installed as ``orcha-sdk`` (and ``emerge``, kept as an alias). Four commands
+only (resist scope creep — test/deploy/login are post-launch):
+
+- ``orcha-sdk init [name]``   scaffold a new agent from the bundled template
+- ``orcha-sdk run [module]``  serve decorated agents locally + register them
+- ``orcha-sdk publish [module]``  register decorated agents against a remote registry
+- ``orcha-sdk validate``  validator demo (``--once`` synthetic attestation)
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import logging
+import os
+import sys
+import threading
+from datetime import UTC, datetime
+from pathlib import Path
+
+from . import __version__
+from .client import DEFAULT_REGISTRY_URL, RegistryError, register
+from .manifest import manifest_yaml
+from .sdk import AgentSpec, clear_registry, registered_agents
+from .server import serve_agent
+
+logger = logging.getLogger("emerge")
+
+_TEMPLATE_DIR = Path(__file__).parent / "templates" / "your-first-agent"
+
+
+def _dan_experimental_enabled() -> bool:
+    """True when ORCHA_DAN_EXPERIMENTAL=1 (experimental network opt-in)."""
+    return os.getenv("ORCHA_DAN_EXPERIMENTAL", "").lower() in ("1", "true", "yes")
+
+
+def _require_dan_experimental(feature: str) -> bool:
+    if _dan_experimental_enabled():
+        return True
+    print(
+        f"emerge: {feature} requires experimental network mode.\n"
+        "  Set ORCHA_DAN_EXPERIMENTAL=1 or network.experimental: true in emerge.yaml.",
+        file=sys.stderr,
+    )
+    return False
+
+
+def _load_module(module_path: str) -> None:
+    """Import a Python file by path so its @emerge.agent decorators register."""
+    path = Path(module_path).resolve()
+    if not path.exists():
+        sys.exit(f"emerge: no such file: {module_path}")
+    sys.path.insert(0, str(path.parent))
+    spec = importlib.util.spec_from_file_location(path.stem, path)
+    if spec is None or spec.loader is None:
+        sys.exit(f"emerge: cannot import {module_path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[path.stem] = module
+    spec.loader.exec_module(module)
+
+
+def _discover(module_path: str) -> list[AgentSpec]:
+    clear_registry()
+    _load_module(module_path)
+    agents = registered_agents()
+    if not agents:
+        sys.exit(
+            f"emerge: no @emerge.agent found in {module_path}. "
+            "Did you decorate a handler?"
+        )
+    return agents
+
+
+def _default_module() -> str:
+    for candidate in ("agent.py", "main.py"):
+        if Path(candidate).exists():
+            return candidate
+    sys.exit(
+        "emerge: no agent.py/main.py here. Pass a module path or run `emerge init`."
+    )
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    name = args.name
+    slug = name.lower().replace(" ", "-")
+    dest = Path(args.dir or slug)
+    if dest.exists() and any(dest.iterdir()):
+        sys.exit(f"emerge: {dest} already exists and is not empty.")
+    dest.mkdir(parents=True, exist_ok=True)
+    for src in _TEMPLATE_DIR.rglob("*"):
+        rel = src.relative_to(_TEMPLATE_DIR)
+        target = dest / rel
+        if src.is_dir():
+            target.mkdir(parents=True, exist_ok=True)
+            continue
+        text = src.read_text(encoding="utf-8")
+        text = text.replace("{{AGENT_NAME}}", name).replace("{{AGENT_SLUG}}", slug)
+        target.write_text(text, encoding="utf-8")
+    print(f"✓ Scaffolded '{name}' in {dest}/")
+    print("  Next:")
+    print(f"    cd {dest}")
+    print("    orcha-sdk run       # serve locally; registers if a registry is up")
+    return 0
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    module = args.module or _default_module()
+    agents = _discover(module)
+    registry_url = args.registry or os.getenv(
+        "ORCHA_REGISTRY_URL", DEFAULT_REGISTRY_URL
+    )
+    token = os.getenv("ORCHA_PAT")
+
+    # Every agent serves in a background thread first: the registry harvests
+    # capabilities from the live endpoint, so it has to be reachable before
+    # register() is called. The main thread parks afterwards — serving a port
+    # that is already bound raises OSError(EADDRINUSE).
+    for spec in agents:
+        serve_agent(spec, block=False)
+        print(f"✓ Serving {spec.name} on http://localhost:{spec.port}  ({spec.did})")
+        if args.register:
+            try:
+                resp = register(
+                    manifest_yaml(spec), registry_url=registry_url, token=token
+                )
+                print(
+                    f"  ✓ Registered with {registry_url}"
+                    + (
+                        f" (agent_id={resp.get('agent_id')})"
+                        if resp.get("agent_id")
+                        else ""
+                    )
+                )
+            except RegistryError as exc:
+                print(f"  ⚠ Registration skipped: {exc}", file=sys.stderr)
+                print(
+                    "    The agent is serving locally regardless. To register it, "
+                    "start the runtime (./scripts/run-all.sh) or pass --no-register "
+                    "to silence this.",
+                    file=sys.stderr,
+                )
+
+    print("\nPress Ctrl+C to stop.")
+    try:
+        threading.Event().wait()
+    except KeyboardInterrupt:
+        print("\nStopped.")
+    return 0
+
+
+def cmd_publish(args: argparse.Namespace) -> int:
+    if getattr(args, "network", None) and not _require_dan_experimental(
+        "emerge publish --network"
+    ):
+        return 1
+    module = args.module or _default_module()
+    agents = _discover(module)
+    registry_url = args.registry or os.getenv("ORCHA_REGISTRY_URL")
+    if not registry_url:
+        sys.exit("emerge publish: pass --registry <url> or set ORCHA_REGISTRY_URL.")
+    token = args.token or os.getenv("ORCHA_PAT")
+    host = args.host
+    failures = 0
+    for spec in agents:
+        try:
+            resp = register(
+                manifest_yaml(spec, host=host), registry_url=registry_url, token=token
+            )
+            print(
+                f"✓ Published {spec.name} → {registry_url}"
+                + (
+                    f" (agent_id={resp.get('agent_id')})"
+                    if resp.get("agent_id")
+                    else ""
+                )
+            )
+        except RegistryError as exc:
+            failures += 1
+            print(f"✗ {spec.name}: {exc}", file=sys.stderr)
+    return 1 if failures else 0
+
+
+def _synthetic_attestation(*, validator_did: str) -> dict:
+    """Build a demo attestation for `emerge validate --once`."""
+    success = True
+    content = "ok"
+    score = 0.85 if success and content and not content.startswith("Error:") else 0.2
+    return {
+        "schema_version": "1.0",
+        "call_id": "call-validate-demo",
+        "agent_id": "did:orcha:agent:demo",
+        "validator_did": validator_did,
+        "success": success,
+        "latency_ms": 42,
+        "judge_score": score,
+        "notes": "spike-heuristic (--once demo)",
+        "observed_at": datetime.now(UTC).isoformat(),
+    }
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    validator_did = args.validator_did or os.getenv(
+        "VALIDATOR_DID", "did:orcha:validator:local"
+    )
+    if args.once:
+        attestation = _synthetic_attestation(validator_did=validator_did)
+        print(json.dumps(attestation, indent=2))
+        print(
+            f"\n✓ Demo attestation for validator {validator_did} "
+            "(subscribe to execution.step_complete for live traffic)"
+        )
+        return 0
+    if not _require_dan_experimental("emerge validate (live mode)"):
+        return 1
+    if args.kafka:
+        print(
+            "emerge validate: Kafka consumer is not wired yet.\n"
+            "  Use --once for a local demo, or run a validator process against "
+            "execution.step_complete when KAFKA_ENABLED=true.",
+            file=sys.stderr,
+        )
+        return 1
+    print(
+        "emerge validate: pass --once for a demo attestation, or --kafka <brokers> "
+        "(consumer TBD).",
+        file=sys.stderr,
+    )
+    return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(description="Orcha agent developer CLI")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    pi = sub.add_parser("init", help="scaffold a new agent from a template")
+    pi.add_argument("name", help="agent name, e.g. 'My Agent'")
+    pi.add_argument("--dir", help="target directory (default: slug of name)")
+    pi.set_defaults(func=cmd_init)
+
+    pr = sub.add_parser(
+        "run", help="serve agents locally + register against local registry"
+    )
+    pr.add_argument(
+        "module", nargs="?", help="path to agent module (default: agent.py/main.py)"
+    )
+    pr.add_argument(
+        "--registry", help=f"registry URL (default: {DEFAULT_REGISTRY_URL})"
+    )
+    pr.add_argument(
+        "--no-register",
+        dest="register",
+        action="store_false",
+        help="serve only; do not register",
+    )
+    pr.set_defaults(func=cmd_run, register=True)
+
+    pp = sub.add_parser("publish", help="register agents against a remote registry")
+    pp.add_argument(
+        "module", nargs="?", help="path to agent module (default: agent.py/main.py)"
+    )
+    pp.add_argument("--registry", help="remote registry URL (or ORCHA_REGISTRY_URL)")
+    pp.add_argument("--token", help="PAT token (or ORCHA_PAT)")
+    pp.add_argument(
+        "--host",
+        default="localhost",
+        help="host advertised in the manifest endpoint (default: localhost)",
+    )
+    pp.add_argument(
+        "--network",
+        help="network bootstrap peer for publish (experimental)",
+    )
+    pp.set_defaults(func=cmd_publish)
+
+    pv = sub.add_parser(
+        "validate",
+        help="run a validator observer node (experimental — --once demo)",
+    )
+    pv.add_argument(
+        "--validator-did",
+        help="validator DID (default: did:orcha:validator:local or VALIDATOR_DID)",
+    )
+    pv.add_argument(
+        "--bootstrap",
+        help="network bootstrap peer (reserved)",
+    )
+    pv.add_argument(
+        "--kafka",
+        help="Kafka bootstrap servers for execution.step_complete (consumer TBD)",
+    )
+    pv.add_argument(
+        "--once",
+        action="store_true",
+        help="emit one synthetic attestation and exit (local demo)",
+    )
+    pv.set_defaults(func=cmd_validate)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    logging.basicConfig(level=os.getenv("EMERGE_LOG_LEVEL", "INFO"))
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

orcha_sdk-0.1.1/src/emerge/client.py

@@ -0,0 +1,71 @@
+"""Minimal registry client — register an agent's emerge.yaml.
+
+Uses only the standard library (urllib) so the SDK stays dependency-light.
+Registration mirrors ``POST /api/v1/agents/register`` (multipart upload of the
+``emerge.yaml`` file, optional ``Authorization: Bearer <PAT>``).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.error
+import urllib.request
+import uuid
+
+logger = logging.getLogger("emerge.client")
+
+DEFAULT_REGISTRY_URL = "http://localhost:8000"
+_REGISTER_PATH = "/api/v1/agents/register"
+
+
+class RegistryError(RuntimeError):
+    """Raised when registration fails."""
+
+
+def _multipart_body(yaml_text: str, *, field: str = "emerge_yaml") -> tuple[bytes, str]:
+    boundary = f"----emerge{uuid.uuid4().hex}"
+    parts = [
+        f"--{boundary}",
+        f'Content-Disposition: form-data; name="{field}"; filename="emerge.yaml"',
+        "Content-Type: application/x-yaml",
+        "",
+        yaml_text,
+        f"--{boundary}--",
+        "",
+    ]
+    body = "\r\n".join(parts).encode("utf-8")
+    return body, boundary
+
+
+def register(
+    yaml_text: str,
+    *,
+    registry_url: str = DEFAULT_REGISTRY_URL,
+    token: str | None = None,
+    timeout: float = 30.0,
+) -> dict:
+    """Register an agent manifest against a registry. Returns the JSON response.
+
+    Raises :class:`RegistryError` on non-2xx responses or transport errors.
+    """
+    url = registry_url.rstrip("/") + _REGISTER_PATH
+    body, boundary = _multipart_body(yaml_text)
+    req = urllib.request.Request(url, data=body, method="POST")  # noqa: S310 - http(s) only
+    req.add_header("Content-Type", f"multipart/form-data; boundary={boundary}")
+    if token:
+        req.add_header("Authorization", f"Bearer {token}")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+            payload = resp.read().decode("utf-8")
+            return json.loads(payload) if payload else {}
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", "replace")
+        raise RegistryError(
+            f"Registry returned {exc.code} for {url}: {detail}"
+        ) from exc
+    except urllib.error.URLError as exc:
+        raise RegistryError(
+            f"Could not reach registry at {registry_url} — is the local stack up? "
+            f"({exc.reason})"
+        ) from exc

orcha_sdk-0.1.1/src/emerge/manifest.py

@@ -0,0 +1,56 @@
+"""Generate an ``emerge.yaml`` manifest from an :class:`AgentSpec`."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .sdk import AgentSpec
+
+SCHEMA_VERSION = "1.0"
+
+
+def build_manifest(spec: AgentSpec, *, host: str = "localhost") -> dict[str, Any]:
+    """Build the manifest dict the registry validates against emerge.yaml schema."""
+    endpoint = f"http://{host}:{spec.port}"
+    manifest: dict[str, Any] = {
+        "schema_version": SCHEMA_VERSION,
+        "identity": {
+            "id": spec.did,
+            "name": spec.name,
+            "version": spec.version,
+            "description": spec.description,
+            "tags": spec.tags,
+        },
+        "protocol": {
+            "type": "a2a",
+            "version": "1.0",
+            "transport": {"type": "http", "endpoint": endpoint},
+        },
+        "health_endpoint": f"{endpoint}/health",
+        "security": {
+            "transport_layer": {"type": "none"},
+            "auth_strategies": [],
+        },
+        "skills": [
+            {
+                "id": s.id,
+                "name": s.name,
+                "description": s.description,
+                "tags": s.tags,
+                "examples": s.examples,
+            }
+            for s in spec.skills
+        ],
+    }
+    if spec.base_fee is not None:
+        manifest["payment"] = {"enabled": True, "base_fee": spec.base_fee}
+    return manifest
+
+
+def manifest_yaml(spec: AgentSpec, *, host: str = "localhost") -> str:
+    """Serialize the manifest to YAML text."""
+    import yaml
+
+    return yaml.safe_dump(
+        build_manifest(spec, host=host), sort_keys=False, default_flow_style=False
+    )

orcha_sdk-0.1.1/src/emerge/sdk.py

@@ -0,0 +1,129 @@
+"""The ``@emerge.agent`` decorator and the in-process agent registry.
+
+Register an agent in three lines::
+
+    import emerge
+
+    @emerge.agent(name="My Agent", description="What I do")
+    def handle(task: str) -> str:
+        return f"handled: {task}"
+
+Then ``emerge run`` (CLI) — or ``emerge.run()`` in ``__main__`` — serves it over
+an A2A-compatible HTTP endpoint and registers it against a local registry.
+"""
+
+from __future__ import annotations
+
+import inspect
+import re
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+Handler = Callable[[str], Any]
+
+
+def _slugify(name: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+    return slug or "agent"
+
+
+@dataclass
+class Skill:
+    """A declared capability, surfaced on the agent card and in the manifest."""
+
+    id: str
+    name: str = ""
+    description: str = ""
+    tags: list[str] = field(default_factory=list)
+    examples: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            self.name = self.id.replace("-", " ").replace("_", " ").title()
+
+
+@dataclass
+class AgentSpec:
+    """Everything the runtime needs to serve, describe, and register an agent."""
+
+    name: str
+    description: str
+    handler: Handler
+    did: str
+    version: str = "0.1.0"
+    port: int = 8900
+    tags: list[str] = field(default_factory=list)
+    skills: list[Skill] = field(default_factory=list)
+    base_fee: str | None = None
+
+    async def invoke(self, task: str) -> str:
+        """Call the handler, awaiting it if it is a coroutine. Returns text."""
+        result = self.handler(task)
+        if inspect.isawaitable(result):
+            result = await result
+        return result if isinstance(result, str) else str(result)
+
+
+# Process-wide registry of decorated agents, in declaration order.
+_AGENTS: list[AgentSpec] = []
+
+
+def agent(
+    _fn: Handler | None = None,
+    *,
+    name: str,
+    description: str,
+    did: str | None = None,
+    version: str = "0.1.0",
+    port: int = 8900,
+    tags: list[str] | None = None,
+    skills: list[Skill | dict[str, Any]] | None = None,
+    base_fee: str | None = None,
+) -> Callable[[Handler], Handler] | Handler:
+    """Register ``fn`` as an Orcha agent. Returns ``fn`` unchanged.
+
+    ``did`` defaults to ``did:orcha:agent:<slug-of-name>``. If no ``skills`` are
+    given, a single skill is derived from the agent name so the agent card is
+    never empty (the registry harvests skills from the card at registration).
+    """
+
+    def decorate(fn: Handler) -> Handler:
+        slug = _slugify(name)
+        resolved_did = did or f"did:orcha:agent:{slug}"
+        resolved_skills: list[Skill] = []
+        for s in skills or []:
+            resolved_skills.append(s if isinstance(s, Skill) else Skill(**s))
+        if not resolved_skills:
+            resolved_skills = [
+                Skill(id=slug, name=name, description=description, tags=tags or [])
+            ]
+        _AGENTS.append(
+            AgentSpec(
+                name=name,
+                description=description,
+                handler=fn,
+                did=resolved_did,
+                version=version,
+                port=port,
+                tags=tags or [],
+                skills=resolved_skills,
+                base_fee=base_fee,
+            )
+        )
+        return fn
+
+    # Support both @agent(...) and bare @agent usage.
+    if _fn is not None:
+        return decorate(_fn)
+    return decorate
+
+
+def registered_agents() -> list[AgentSpec]:
+    """Return all agents registered via the decorator, in declaration order."""
+    return list(_AGENTS)
+
+
+def clear_registry() -> None:
+    """Test helper — drop all registered agents."""
+    _AGENTS.clear()

orcha_sdk-0.1.1/src/emerge/server.py

@@ -0,0 +1,190 @@
+"""A dependency-light A2A-compatible HTTP server for SDK agents.
+
+Implements the same wire contract the Orcha SuperAgent speaks to A2A agents,
+using only the standard library so ``emerge run`` has no heavy dependencies:
+
+- ``GET  /health``                  → liveness probe
+- ``GET  /.well-known/agent.json``  → A2A agent card (registry harvests skills)
+- ``POST /``                        → JSON-RPC 2.0: ``message/send`` + ``tasks/get``
+
+Tasks complete synchronously, so ``message/send`` returns a completed task and
+``tasks/get`` reads it back from a small in-memory store.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import threading
+import uuid
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+from .sdk import AgentSpec
+
+logger = logging.getLogger("emerge.server")
+
+
+def agent_card(spec: AgentSpec, host: str = "localhost") -> dict[str, Any]:
+    """Build the A2A agent card served at /.well-known/agent.json."""
+    return {
+        "schemaVersion": "1.0",
+        "name": spec.name,
+        "description": spec.description,
+        "url": f"http://{host}:{spec.port}",
+        "version": spec.version,
+        "capabilities": {"streaming": False, "pushNotifications": False},
+        "skills": [
+            {
+                "id": s.id,
+                "name": s.name,
+                "description": s.description,
+                "tags": s.tags,
+                "examples": s.examples,
+            }
+            for s in spec.skills
+        ],
+    }
+
+
+def _extract_text(message: dict[str, Any]) -> str:
+    parts = message.get("parts", []) or []
+    texts = [
+        p.get("text", "")
+        for p in parts
+        if p.get("kind") == "text" or p.get("type") == "text"
+    ]
+    return " ".join(texts).strip()
+
+
+def _completed_task(task_id: str, answer: str) -> dict[str, Any]:
+    return {
+        "id": task_id,
+        "status": {"state": "completed"},
+        "artifacts": [{"parts": [{"kind": "text", "text": answer}]}],
+    }
+
+
+def _failed_task(task_id: str, error: str) -> dict[str, Any]:
+    return {
+        "id": task_id,
+        "status": {
+            "state": "failed",
+            "message": {
+                "role": "agent",
+                "parts": [{"kind": "text", "text": f"Error: {error}"}],
+            },
+        },
+    }
+
+
+def _make_handler(spec: AgentSpec, host: str):
+    card = agent_card(spec, host=host)
+    task_store: dict[str, dict[str, Any]] = {}
+
+    class Handler(BaseHTTPRequestHandler):
+        protocol_version = "HTTP/1.1"
+
+        def log_message(self, fmt: str, *args: Any) -> None:  # quieter logs
+            logger.debug("%s - %s", self.address_string(), fmt % args)
+
+        def _send_json(self, payload: dict[str, Any], status: int = 200) -> None:
+            body = json.dumps(payload).encode("utf-8")
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.end_headers()
+            self.wfile.write(body)
+
+        def do_GET(self) -> None:  # noqa: N802
+            if self.path == "/health":
+                self._send_json(
+                    {"status": "healthy", "agent": spec.name, "version": spec.version}
+                )
+            elif self.path == "/.well-known/agent.json":
+                self._send_json(card)
+            else:
+                self._send_json({"error": "not found"}, status=404)
+
+        def do_POST(self) -> None:  # noqa: N802
+            length = int(self.headers.get("Content-Length", 0) or 0)
+            try:
+                body = json.loads(self.rfile.read(length) or b"{}")
+            except json.JSONDecodeError:
+                self._send_json(
+                    {
+                        "jsonrpc": "2.0",
+                        "id": "",
+                        "error": {"code": -32700, "message": "Parse error"},
+                    },
+                    status=400,
+                )
+                return
+
+            rpc_id = body.get("id", "")
+            method = body.get("method", "")
+            params = body.get("params", {}) or {}
+
+            if method == "message/send":
+                message = params.get("message", {}) or {}
+                task_id = (
+                    params.get("taskId") or message.get("taskId") or str(uuid.uuid4())
+                )
+                query = _extract_text(message)
+                try:
+                    answer = asyncio.run(spec.invoke(query))
+                    task = _completed_task(task_id, answer)
+                except Exception as exc:  # noqa: BLE001 - surface as failed task
+                    logger.exception("Handler raised for task %s", task_id)
+                    task = _failed_task(task_id, str(exc))
+                task_store[task_id] = task
+                self._send_json({"jsonrpc": "2.0", "id": rpc_id, "result": task})
+            elif method == "tasks/get":
+                task_id = params.get("id", "")
+                task = task_store.get(task_id)
+                if task is None:
+                    self._send_json(
+                        {
+                            "jsonrpc": "2.0",
+                            "id": rpc_id,
+                            "error": {
+                                "code": -32602,
+                                "message": f"Task {task_id!r} not found",
+                            },
+                        }
+                    )
+                else:
+                    self._send_json({"jsonrpc": "2.0", "id": rpc_id, "result": task})
+            else:
+                self._send_json(
+                    {
+                        "jsonrpc": "2.0",
+                        "id": rpc_id,
+                        "error": {
+                            "code": -32601,
+                            "message": f"Method not found: {method!r}",
+                        },
+                    }
+                )
+
+    return Handler
+
+
+def serve_agent(
+    spec: AgentSpec, host: str = "0.0.0.0", *, block: bool = True
+) -> ThreadingHTTPServer:
+    """Start an HTTP server for a single agent. Returns the server.
+
+    When ``block`` is False the server runs in a daemon thread (useful for tests
+    and multi-agent serving); otherwise this call blocks via ``serve_forever``.
+    """
+    card_host = os.getenv("EMERGE_ADVERTISE_HOST", "localhost")
+    httpd = ThreadingHTTPServer((host, spec.port), _make_handler(spec, card_host))
+    if block:
+        httpd.serve_forever()
+    else:
+        threading.Thread(target=httpd.serve_forever, daemon=True).start()
+    return httpd

orcha_sdk-0.1.1/src/emerge/templates/your-first-agent/README.md

@@ -0,0 +1,31 @@
+# {{AGENT_NAME}}
+
+Your first Orcha agent, scaffolded with `orcha-sdk init`.
+
+## Run it
+
+```bash
+pip install orcha-sdk        # if you haven't already
+orcha-sdk run                   # serve + register against http://localhost:8000
+```
+
+Or serve without registering:
+
+```bash
+orcha-sdk run --no-register
+```
+
+## What's here
+
+- `agent.py` — the agent. A decorated `handle(task)` function is the whole thing.
+- `requirements.txt` — just `orcha-sdk`.
+
+## Next steps
+
+1. Edit `handle()` in `agent.py` with your real logic.
+2. Update the `description` and `skills` — the planner uses them to route to you.
+3. `orcha-sdk publish --registry <url>` to register against a remote registry.
+
+DID: `did:orcha:agent:{{AGENT_SLUG}}` · Manifest: generated from the decorator.
+See the [bridges guide](https://metaorcha.ai/docs)
+to connect a whole other protocol.

orcha_sdk-0.1.1/src/emerge/templates/your-first-agent/agent.py

@@ -0,0 +1,55 @@
+"""{{AGENT_NAME}} — your first Orcha agent.
+
+An agent is just a function that takes a natural-language `task` string and
+returns a result string. The `@emerge.agent` decorator does the rest:
+
+  - gives the agent a DID (did:orcha:agent:{{AGENT_SLUG}})
+  - generates the emerge.yaml manifest the registry validates
+  - serves it over an A2A-compatible HTTP endpoint when you run it
+
+Try it:
+
+    orcha-sdk run            # serve + register against the local registry
+    orcha-sdk run --no-register   # serve only
+
+Then ask the orchestrator to do something this agent can handle, or call it
+directly:
+
+    curl -s localhost:8900/.well-known/agent.json
+"""
+
+from __future__ import annotations
+
+import emerge
+
+
+@emerge.agent(
+    name="{{AGENT_NAME}}",
+    description="Describe in one sentence what this agent does — the planner reads this to decide when to route to you.",
+    version="0.1.0",
+    port=8900,
+    tags=["example"],
+    # Declare the things your agent can do. Skills are surfaced on the agent
+    # card and harvested by the registry. Good descriptions + examples make the
+    # planner route to you correctly.
+    skills=[
+        {
+            "id": "echo",
+            "name": "Echo",
+            "description": "Echo the task back. Replace this with your real capability.",
+            "examples": ["say hello", "repeat after me: orcha"],
+        }
+    ],
+    # Uncomment to charge per invocation (mock mode by default — no wallet needed):
+    # base_fee="0.05",
+)
+def handle(task: str) -> str:
+    """Handle one task. Replace the body with your real logic.
+
+    The handler may be sync or async (`async def handle(...)`).
+    """
+    return f"{{AGENT_NAME}} received: {task}"
+
+
+if __name__ == "__main__":
+    emerge.run()

orcha_sdk-0.1.1/src/emerge/templates/your-first-agent/requirements.txt

@@ -0,0 +1 @@
+orcha-sdk>=0.1.0

orcha_sdk-0.1.1/tests/test_sdk.py

@@ -0,0 +1,125 @@
+"""End-to-end-ish tests for the emerge SDK: decorator → manifest → A2A server."""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+
+import pytest
+
+import emerge
+from emerge.manifest import build_manifest
+from emerge.sdk import clear_registry, registered_agents
+from emerge.server import agent_card, serve_agent
+
+
+@pytest.fixture(autouse=True)
+def _clean_registry():
+    clear_registry()
+    yield
+    clear_registry()
+
+
+def test_decorator_registers_agent_with_default_did():
+    @emerge.agent(name="My Agent", description="does things")
+    def handle(task: str) -> str:
+        return task
+
+    agents = registered_agents()
+    assert len(agents) == 1
+    spec = agents[0]
+    assert spec.did == "did:orcha:agent:my-agent"
+    assert spec.name == "My Agent"
+    # No explicit skills → one derived skill so the agent card is never empty.
+    assert spec.skills and spec.skills[0].id == "my-agent"
+
+
+def test_decorator_returns_callable_unchanged():
+    @emerge.agent(name="X", description="d")
+    def handle(task: str) -> str:
+        return "ok:" + task
+
+    assert handle("hi") == "ok:hi"
+
+
+def test_manifest_shape_matches_registry_schema():
+    @emerge.agent(name="Priced", description="d", base_fee="0.10", port=8901)
+    def handle(task: str) -> str:
+        return task
+
+    m = build_manifest(registered_agents()[0])
+    assert m["schema_version"] == "1.0"
+    assert m["identity"]["id"] == "did:orcha:agent:priced"
+    assert m["protocol"]["type"] == "a2a"
+    assert m["protocol"]["transport"]["endpoint"] == "http://localhost:8901"
+    assert m["health_endpoint"] == "http://localhost:8901/health"
+    assert m["payment"] == {"enabled": True, "base_fee": "0.10"}
+
+
+def test_agent_card_is_valid():
+    @emerge.agent(name="Carded", description="d", port=8902)
+    def handle(task: str) -> str:
+        return task
+
+    card = agent_card(registered_agents()[0])
+    assert card["name"] == "Carded"
+    assert card["skills"]
+    assert card["url"] == "http://localhost:8902"
+
+
+def _post_jsonrpc(port: int, method: str, params: dict) -> dict:
+    body = json.dumps({"jsonrpc": "2.0", "id": "1", "method": method, "params": params}).encode()
+    req = urllib.request.Request(
+        f"http://127.0.0.1:{port}/", data=body,
+        headers={"Content-Type": "application/json"}, method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=5) as resp:
+        return json.loads(resp.read())
+
+
+def _get(port: int, path: str) -> dict:
+    with urllib.request.urlopen(f"http://127.0.0.1:{port}{path}", timeout=5) as resp:
+        return json.loads(resp.read())
+
+
+def test_server_serves_health_card_and_executes_task():
+    port = 8943
+
+    @emerge.agent(name="Live Agent", description="echoes", port=port)
+    def handle(task: str) -> str:
+        return f"echo: {task}"
+
+    httpd = serve_agent(registered_agents()[0], host="127.0.0.1", block=False)
+    try:
+        assert _get(port, "/health")["status"] == "healthy"
+        assert _get(port, "/.well-known/agent.json")["name"] == "Live Agent"
+
+        result = _post_jsonrpc(port, "message/send", {
+            "message": {"parts": [{"kind": "text", "text": "hello"}]},
+        })["result"]
+        assert result["status"]["state"] == "completed"
+        answer = result["artifacts"][0]["parts"][0]["text"]
+        assert answer == "echo: hello"
+
+        # tasks/get reads the same task back.
+        fetched = _post_jsonrpc(port, "tasks/get", {"id": result["id"]})["result"]
+        assert fetched["id"] == result["id"]
+    finally:
+        httpd.shutdown()
+
+
+def test_async_handler_supported():
+    port = 8944
+
+    @emerge.agent(name="Async Agent", description="async", port=port)
+    async def handle(task: str) -> str:
+        return f"async: {task}"
+
+    httpd = serve_agent(registered_agents()[0], host="127.0.0.1", block=False)
+    try:
+        result = _post_jsonrpc(port, "message/send", {
+            "message": {"parts": [{"type": "text", "text": "x"}]},
+        })["result"]
+        assert result["artifacts"][0]["parts"][0]["text"] == "async: x"
+    finally:
+        httpd.shutdown()