nebelus 0.1.1__tar.gz

nebelus-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+# Publishes the `nebelus` package to PyPI via Trusted Publishing (OIDC) —
+# no API token exists anywhere. Requires the PyPI-side "pending publisher"
+# to be configured for: owner Nebelus, repo nebelus-python, workflow
+# release.yml, environment pypi.
+name: release
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: pytest tests -q
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC for PyPI Trusted Publishing
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

nebelus-0.1.1/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: nebelus
+Version: 0.1.1
+Summary: Nebelus Agents API — build, edit, and ship governed AI agents from code
+Author-email: Nebelus <support@nebelus.ai>
+License: Proprietary
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.5
+Provides-Extra: dev
+Requires-Dist: langgraph>=0.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == 'langgraph'
+Description-Content-Type: text/markdown
+
+# Nebelus Agents API — Python SDK
+
+Build, edit, and ship governed AI agents from code. Every agent you create here is the
+same artifact your team sees in the Nebelus portal — one construction service, every
+surface, your organization's governance applied identically.
+
+```python
+from nebelus import Nebelus, AgentManifest
+
+nb = Nebelus()  # NEBELUS_API_KEY + NEBELUS_BASE_URL (default https://api.nebelus.ai)
+
+# Discover what this organization can build — machine-readable.
+info = nb.describe()
+
+manifest = AgentManifest(
+    name="Return-policy concierge",
+    model_id="claude-haiku-4-5",
+    system_message="Answer from the return policy. Escalate anything ambiguous.",
+)
+agent = nb.apply(manifest)               # create-or-update, key-wise merge — never clobbers portal edits
+print(nb.agents.probe(agent.id, "Can I return a jacket after 20 days?").reply)
+# Deploying is a human act unless your org opted in to programmatic deployment:
+# nb.agents.deploy(agent.id)             # needs the api.construction.deploy scope + the org opt-in
+```
+
+Keys: Nebelus portal → Settings → API keys (administrator-managed). Scopes:
+`api.construction.read`, `api.construction.write`, and `api.construction.deploy`.
+Your Build Envelope (if your organization uses one) applies to code exactly as it applies
+to every other surface.
+
+## CLI
+
+Everything above is also a command (`pip install nebelus` puts `nebelus` on your PATH):
+
+```bash
+nebelus describe                       # everything your org can build, machine-readable
+nebelus catalog --view tools --query crm
+nebelus apply agent.py                 # a file defining `manifest = AgentManifest(...)`
+nebelus diff agent.py                  # what apply would change ("in sync" when nothing)
+nebelus validate <agent-id>            # pre-flight findings before you probe or deploy
+nebelus probe <agent-id> "Hi there"    # run the draft through the real runtime
+nebelus export <agent-id> > agent.py   # a live agent as a maintainable Python manifest
+nebelus deploy <agent-id>              # needs the deploy scope + the org's opt-in
+```
+
+## Two-way with the portal
+
+`nebelus export` (or `nebelus.export_to_code`) turns any live agent — including one a
+colleague built visually — into a Python manifest you own in git. `apply` takes it back.
+The merge contract makes this safe in both directions: a manifest only manages the fields
+it declares, so portal edits to everything else survive every apply, and `diff` never
+reports server-side normalization as drift.
+
+## Coming from LangGraph
+
+`from_langgraph` translates a `StateGraph`'s topology into a Nebelus workflow — nodes,
+edges, and conditional-edge targets map mechanically (both sides share the
+`__start__`/`__end__` sentinels). What a node *does* and how a router *decides* live in
+your Python, so you declare those explicitly; anything with no declarative equivalent
+stays in your code and attaches to the agent as an MCP server or custom API endpoint.
+Incomplete translations return named diagnostics instead of a manifest — nothing is
+guessed:
+
+```python
+from nebelus import Nebelus, from_langgraph
+
+t = from_langgraph(
+    my_state_graph,
+    node_map={"triage": {"type": "agent", "config": {"system_prompt": "...", "model_id": "claude-haiku-4-5"}}},
+    router_map={"triage": {"conditions": [{"expression": "...", "target": "billing"}],
+                           "default_target": "general"}},
+    manifest_id="triage-v1", name="Triage", model_id="claude-haiku-4-5",
+)
+if t.complete:
+    Nebelus().apply(t.manifest)
+else:
+    print("\n".join(t.diagnostics))   # names every unmapped node and undeclared router
+```
+
+Install the source-graph dependency with `pip install "nebelus[langgraph]"`.
+
+## GitHub Action
+
+Keep manifests in git and let CI hold them in sync — PRs show the diff, merges apply it
+(see `examples/agents-apply.yml`):
+
+```yaml
+- uses: Nebelus/nebelus-python/action@main
+  with:
+    manifests: agents/*.py
+    api-key: ${{ secrets.NEBELUS_API_KEY }}
+    mode: ${{ github.event_name == 'push' && 'apply' || 'diff' }}
+```
+
+## Rate limits
+
+The API rate-limits per key (generous defaults; probes are tighter since each spends real
+model money). The SDK waits out short `Retry-After` pauses automatically and raises
+`nebelus.RateLimited` (with `.retry_after`) when the pause is too long to hold in-process.

nebelus-0.1.1/README.md

@@ -0,0 +1,99 @@
+# Nebelus Agents API — Python SDK
+
+Build, edit, and ship governed AI agents from code. Every agent you create here is the
+same artifact your team sees in the Nebelus portal — one construction service, every
+surface, your organization's governance applied identically.
+
+```python
+from nebelus import Nebelus, AgentManifest
+
+nb = Nebelus()  # NEBELUS_API_KEY + NEBELUS_BASE_URL (default https://api.nebelus.ai)
+
+# Discover what this organization can build — machine-readable.
+info = nb.describe()
+
+manifest = AgentManifest(
+    name="Return-policy concierge",
+    model_id="claude-haiku-4-5",
+    system_message="Answer from the return policy. Escalate anything ambiguous.",
+)
+agent = nb.apply(manifest)               # create-or-update, key-wise merge — never clobbers portal edits
+print(nb.agents.probe(agent.id, "Can I return a jacket after 20 days?").reply)
+# Deploying is a human act unless your org opted in to programmatic deployment:
+# nb.agents.deploy(agent.id)             # needs the api.construction.deploy scope + the org opt-in
+```
+
+Keys: Nebelus portal → Settings → API keys (administrator-managed). Scopes:
+`api.construction.read`, `api.construction.write`, and `api.construction.deploy`.
+Your Build Envelope (if your organization uses one) applies to code exactly as it applies
+to every other surface.
+
+## CLI
+
+Everything above is also a command (`pip install nebelus` puts `nebelus` on your PATH):
+
+```bash
+nebelus describe                       # everything your org can build, machine-readable
+nebelus catalog --view tools --query crm
+nebelus apply agent.py                 # a file defining `manifest = AgentManifest(...)`
+nebelus diff agent.py                  # what apply would change ("in sync" when nothing)
+nebelus validate <agent-id>            # pre-flight findings before you probe or deploy
+nebelus probe <agent-id> "Hi there"    # run the draft through the real runtime
+nebelus export <agent-id> > agent.py   # a live agent as a maintainable Python manifest
+nebelus deploy <agent-id>              # needs the deploy scope + the org's opt-in
+```
+
+## Two-way with the portal
+
+`nebelus export` (or `nebelus.export_to_code`) turns any live agent — including one a
+colleague built visually — into a Python manifest you own in git. `apply` takes it back.
+The merge contract makes this safe in both directions: a manifest only manages the fields
+it declares, so portal edits to everything else survive every apply, and `diff` never
+reports server-side normalization as drift.
+
+## Coming from LangGraph
+
+`from_langgraph` translates a `StateGraph`'s topology into a Nebelus workflow — nodes,
+edges, and conditional-edge targets map mechanically (both sides share the
+`__start__`/`__end__` sentinels). What a node *does* and how a router *decides* live in
+your Python, so you declare those explicitly; anything with no declarative equivalent
+stays in your code and attaches to the agent as an MCP server or custom API endpoint.
+Incomplete translations return named diagnostics instead of a manifest — nothing is
+guessed:
+
+```python
+from nebelus import Nebelus, from_langgraph
+
+t = from_langgraph(
+    my_state_graph,
+    node_map={"triage": {"type": "agent", "config": {"system_prompt": "...", "model_id": "claude-haiku-4-5"}}},
+    router_map={"triage": {"conditions": [{"expression": "...", "target": "billing"}],
+                           "default_target": "general"}},
+    manifest_id="triage-v1", name="Triage", model_id="claude-haiku-4-5",
+)
+if t.complete:
+    Nebelus().apply(t.manifest)
+else:
+    print("\n".join(t.diagnostics))   # names every unmapped node and undeclared router
+```
+
+Install the source-graph dependency with `pip install "nebelus[langgraph]"`.
+
+## GitHub Action
+
+Keep manifests in git and let CI hold them in sync — PRs show the diff, merges apply it
+(see `examples/agents-apply.yml`):
+
+```yaml
+- uses: Nebelus/nebelus-python/action@main
+  with:
+    manifests: agents/*.py
+    api-key: ${{ secrets.NEBELUS_API_KEY }}
+    mode: ${{ github.event_name == 'push' && 'apply' || 'diff' }}
+```
+
+## Rate limits
+
+The API rate-limits per key (generous defaults; probes are tighter since each spends real
+model money). The SDK waits out short `Retry-After` pauses automatically and raises
+`nebelus.RateLimited` (with `.retry_after`) when the pause is too long to hold in-process.

nebelus-0.1.1/action/action.yml

@@ -0,0 +1,39 @@
+name: "Nebelus Agents Apply"
+description: "Diff or apply Nebelus agent manifests (.py defining `manifest = AgentManifest(...)`) from your repo."
+branding:
+  icon: upload-cloud
+  color: orange
+inputs:
+  manifests:
+    description: "Whitespace-separated manifest file paths"
+    required: true
+  api-key:
+    description: "Nebelus API key (store as a repo secret)"
+    required: true
+  base-url:
+    description: "API base URL"
+    required: false
+    default: "https://api.nebelus.ai"
+  mode:
+    description: "'diff' (report only — use on pull_request) or 'apply' (use on push to main)"
+    required: false
+    default: "diff"
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+    - shell: bash
+      run: pip install --quiet nebelus
+    - shell: bash
+      env:
+        NEBELUS_API_KEY: ${{ inputs.api-key }}
+        NEBELUS_BASE_URL: ${{ inputs.base-url }}
+      run: |
+        set -euo pipefail
+        for f in ${{ inputs.manifests }}; do
+          echo "::group::${{ inputs.mode }} $f"
+          nebelus "${{ inputs.mode }}" "$f"
+          echo "::endgroup::"
+        done

nebelus-0.1.1/examples/agents-apply.yml

@@ -0,0 +1,20 @@
+# Copy to .github/workflows/ in the repo that holds your agent manifests.
+# PRs show the diff; merges to main apply it. Deploys stay a human act unless
+# your org opted in and the key carries the deploy scope.
+name: Agents
+on:
+  pull_request:
+    paths: ["agents/**.py"]
+  push:
+    branches: [main]
+    paths: ["agents/**.py"]
+jobs:
+  agents:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Nebelus/nebelus-python/action@main
+        with:
+          manifests: agents/*.py
+          api-key: ${{ secrets.NEBELUS_API_KEY }}
+          mode: ${{ github.event_name == 'push' && 'apply' || 'diff' }}

nebelus-0.1.1/examples/triage_workflow.py

@@ -0,0 +1,34 @@
+"""A complete workflow agent as code — apply with `nebelus apply examples/triage_workflow.py`."""
+
+from nebelus import AgentManifest
+
+manifest = AgentManifest(
+    manifest_id="triage-example-v1",
+    name="Support triage",
+    model_id="claude-haiku-4-5",
+    pattern_type="workflow",
+    description="Routes billing questions to a specialist, everything else to a generalist.",
+    pattern_config={
+        "nodes": [
+            {"name": "triage", "type": "agent",
+             "config": {"system_prompt": "Classify the request as 'billing' or 'general'. Reply with exactly one word.",
+                        "model_id": "claude-haiku-4-5"}},
+            {"name": "router", "type": "condition",
+             "config": {"conditions": [{"expression": "'billing' in str(state.get('triage_out','')).lower()",
+                                        "target": "billing"}],
+                        "default_target": "general"}},
+            {"name": "billing", "type": "agent",
+             "config": {"system_prompt": "You are the billing specialist. Be precise.",
+                        "model_id": "claude-haiku-4-5"}},
+            {"name": "general", "type": "agent",
+             "config": {"system_prompt": "You are the general assistant. Be brief.",
+                        "model_id": "claude-haiku-4-5"}},
+        ],
+        "edges": [
+            {"from": "__start__", "to": "triage"},
+            {"from": "triage", "to": "router"},
+            {"from": "billing", "to": "__end__"},
+            {"from": "general", "to": "__end__"},
+        ],
+    },
+)

nebelus-0.1.1/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nebelus"
+version = "0.1.1"
+description = "Nebelus Agents API — build, edit, and ship governed AI agents from code"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [{ name = "Nebelus", email = "support@nebelus.ai" }]
+dependencies = ["httpx>=0.27", "pydantic>=2.5"]
+
+[project.scripts]
+nebelus = "nebelus.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "respx>=0.21", "ruff>=0.6", "langgraph>=0.2"]
+langgraph = ["langgraph>=0.2"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nebelus"]
+
+[tool.ruff]
+line-length = 120

nebelus-0.1.1/src/nebelus/__init__.py

@@ -0,0 +1,22 @@
+"""Nebelus Agents API — official Python SDK."""
+
+from ._transport import NebelusAPIError, NotFound, RateLimited
+from .client import Nebelus
+from .export import export_to_code
+from .langgraph import Translation, from_langgraph
+from .models import Agent, AgentManifest, ProbeResult, ValidationResult
+
+__version__ = "0.1.1"
+__all__ = [
+    "Agent",
+    "AgentManifest",
+    "Nebelus",
+    "NebelusAPIError",
+    "NotFound",
+    "ProbeResult",
+    "RateLimited",
+    "Translation",
+    "ValidationResult",
+    "export_to_code",
+    "from_langgraph",
+]

nebelus-0.1.1/src/nebelus/_transport.py

@@ -0,0 +1,103 @@
+"""HTTP transport: auth, errors-as-exceptions with the API's machine payload intact."""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+
+import httpx
+
+DEFAULT_BASE_URL = "https://api.nebelus.ai"
+API_PREFIX = "/api/v1/construction"
+
+# 429s are retried automatically when the server's Retry-After is short enough
+# to wait out in-process; longer waits surface as RateLimited for the caller.
+MAX_RETRY_AFTER_SECONDS = 30.0
+MAX_RATE_LIMIT_RETRIES = 2
+
+
+class NebelusAPIError(Exception):
+    """Any non-2xx from the API. Carries the FULL machine-readable payload:
+    `detail` (human reason), and when present `envelope` ({blocked, requested,
+    allowed_hint}), `blocked` (opt-in gates), etc."""
+
+    def __init__(self, status_code: int, payload: Any):
+        self.status_code = status_code
+        self.payload = payload if isinstance(payload, dict) else {"detail": str(payload)}
+        super().__init__(f"[{status_code}] {self.payload.get('detail') or self.payload}")
+
+    @property
+    def detail(self) -> str:
+        return str(self.payload.get("detail", ""))
+
+    @property
+    def envelope(self) -> dict | None:
+        """The Build Envelope refusal payload, when the refusal came from one."""
+        return self.payload.get("envelope")
+
+    @property
+    def blocked(self) -> str | None:
+        return self.payload.get("blocked")
+
+
+class NotFound(NebelusAPIError):
+    pass
+
+
+class RateLimited(NebelusAPIError):
+    """429 that could not be waited out in-process. `retry_after` is the
+    server's requested pause in seconds, when it sent one."""
+
+    def __init__(self, status_code: int, payload: Any, retry_after: float | None = None):
+        super().__init__(status_code, payload)
+        self.retry_after = retry_after
+
+
+class Transport:
+    def __init__(self, api_key: str | None = None, base_url: str | None = None, timeout: float = 60.0):
+        self.api_key = api_key or os.environ.get("NEBELUS_API_KEY") or ""
+        if not self.api_key:
+            raise ValueError("No API key. Pass api_key= or set NEBELUS_API_KEY.")
+        self.base_url = (base_url or os.environ.get("NEBELUS_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._client = httpx.Client(
+            base_url=f"{self.base_url}{API_PREFIX}",
+            headers={"Authorization": f"Bearer {self.api_key}", "User-Agent": "nebelus-python/0.1.1"},
+            timeout=timeout,
+        )
+
+    def request(self, method: str, path: str, *, json: Any = None, params: Any = None) -> Any:
+        for attempt in range(MAX_RATE_LIMIT_RETRIES + 1):
+            r = self._client.request(method, path, json=json, params=params)
+            if r.status_code != 429:
+                break
+            retry_after = _retry_after_seconds(r)
+            if attempt == MAX_RATE_LIMIT_RETRIES or retry_after is None or retry_after > MAX_RETRY_AFTER_SECONDS:
+                raise RateLimited(429, _body_of(r), retry_after=retry_after)
+            time.sleep(retry_after)
+        body = _body_of(r)
+        if r.status_code == 404:
+            raise NotFound(r.status_code, body)
+        if r.status_code >= 400:
+            raise NebelusAPIError(r.status_code, body)
+        return body
+
+    def close(self) -> None:
+        self._client.close()
+
+
+def _body_of(r: httpx.Response) -> Any:
+    try:
+        return r.json()
+    except Exception:  # noqa: BLE001
+        return r.text
+
+
+def _retry_after_seconds(r: httpx.Response) -> float | None:
+    raw = r.headers.get("Retry-After")
+    if raw is None:
+        return None
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        return None

nebelus-0.1.1/src/nebelus/cli.py

@@ -0,0 +1,85 @@
+"""`nebelus` — the CLI over the SDK. Same auth (NEBELUS_API_KEY / NEBELUS_BASE_URL)."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+from .client import Nebelus, NebelusAPIError
+from .export import export_to_code
+from .models import AgentManifest
+
+
+def _load_manifest(path: str) -> AgentManifest:
+    p = Path(path)
+    if p.suffix == ".json":
+        return AgentManifest.model_validate(json.loads(p.read_text()))
+    spec = importlib.util.spec_from_file_location("nebelus_manifest", p)
+    mod = importlib.util.module_from_spec(spec)  # type: ignore[arg-type]
+    spec.loader.exec_module(mod)  # type: ignore[union-attr]
+    manifest = getattr(mod, "manifest", None)
+    if not isinstance(manifest, AgentManifest):
+        raise SystemExit(f"{path} must define `manifest = AgentManifest(...)`")
+    return manifest
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="nebelus", description="Nebelus Agents API CLI")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("describe", help="everything buildable in this org, machine-readable")
+    c = sub.add_parser("catalog", help="org catalog")
+    c.add_argument("--view", default="models")
+    c.add_argument("--query")
+    a = sub.add_parser("apply", help="create-or-update from a manifest (.py or .json)")
+    a.add_argument("path")
+    d = sub.add_parser("diff", help="what apply would change")
+    d.add_argument("path")
+    p = sub.add_parser("probe", help="run the draft for real")
+    p.add_argument("agent_id")
+    p.add_argument("message")
+    dep = sub.add_parser("deploy", help="deploy (needs org opt-in + deploy scope)")
+    dep.add_argument("agent_id")
+    e = sub.add_parser("export", help="export a live agent as a Python manifest")
+    e.add_argument("agent_id")
+    v = sub.add_parser("validate", help="pre-flight findings")
+    v.add_argument("agent_id")
+    args = ap.parse_args(argv)
+
+    nb = Nebelus()
+    try:
+        if args.cmd == "describe":
+            print(json.dumps(nb.describe(), indent=2, default=str))
+        elif args.cmd == "catalog":
+            print(json.dumps(nb.catalog(view=args.view, query=args.query), indent=2, default=str))
+        elif args.cmd == "apply":
+            agent = nb.apply(_load_manifest(args.path))
+            print(f"{agent.id} {agent.status}")
+        elif args.cmd == "diff":
+            changes = nb.diff(_load_manifest(args.path))
+            print(json.dumps(changes, indent=2, default=str) if changes else "in sync")
+        elif args.cmd == "probe":
+            r = nb.agents.probe(args.agent_id, args.message)
+            print(r.reply or r.model_dump())
+        elif args.cmd == "deploy":
+            print(json.dumps(nb.agents.deploy(args.agent_id)))
+        elif args.cmd == "validate":
+            print(json.dumps(nb.agents.validate(args.agent_id).model_dump(), indent=2))
+        elif args.cmd == "export":
+            print(export_to_code(nb.agents.get(args.agent_id)))
+    except NebelusAPIError as exc:
+        print(f"error [{exc.status_code}]: {exc.detail}", file=sys.stderr)
+        if exc.envelope:
+            print(f"envelope: {json.dumps(exc.envelope)}", file=sys.stderr)
+        if exc.blocked:
+            print(f"blocked: {exc.blocked}", file=sys.stderr)
+        return 1
+    finally:
+        nb.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())