agentopology 0.1.0

package/examples/scheduled-monitor.at

@@ -0,0 +1,193 @@
+# Scheduled Monitor — demonstrates schedule, interfaces, sandbox, and fallback-chain
+# A monitoring topology that runs on cron, reports to Slack, and uses sandboxed agents.
+
+topology scheduled-monitor : [pipeline, fan-out] {
+
+  meta {
+    version: "1.0"
+    description: "Automated monitoring pipeline with scheduled jobs, external interfaces, sandboxing, and model fallback"
+    domain: devops
+  }
+
+  orchestrator {
+    model: opus
+    handles: [monitor, gen-report, alert]
+    outputs {
+      severity: critical | warning | info
+    }
+  }
+
+  roles {
+    collector: "Gather metrics and health data from monitored systems"
+    analyzer: "Analyze collected data for anomalies and trends"
+    reporter: "Generate human-readable reports and summaries"
+    alerter: "Send alerts to external channels when thresholds are breached"
+  }
+
+  action monitor {
+    kind: inline
+    description: "Collect and analyze system health"
+  }
+
+  action gen-report {
+    kind: report
+    description: "Generate monitoring report"
+  }
+
+  action alert {
+    kind: external
+    source: "scripts/send-alert.sh"
+    description: "Dispatch alert to configured channels"
+  }
+
+  agent collector {
+    model: sonnet
+    phase: 1
+    role: collector
+    tools: [Read, Bash, WebFetch]
+    writes: ["workspace/metrics/"]
+    sandbox: docker
+    outputs {
+      status: healthy | degraded | critical
+    }
+    description: "Collects metrics from configured endpoints"
+  }
+
+  agent analyzer {
+    model: opus
+    phase: 2
+    role: analyzer
+    tools: [Read, Grep]
+    reads: ["workspace/metrics/"]
+    writes: ["workspace/analysis/"]
+    sandbox: network-only
+    fallback-chain: [sonnet, haiku]
+    outputs {
+      severity: critical | warning | info
+    }
+    description: "Analyzes collected metrics for anomalies"
+  }
+
+  agent reporter {
+    model: sonnet
+    phase: 3
+    role: reporter
+    tools: [Read, Write]
+    reads: ["workspace/analysis/"]
+    writes: ["workspace/reports/"]
+    sandbox: true
+    description: "Generates summary reports from analysis"
+  }
+
+  agent alerter {
+    model: haiku
+    phase: 3
+    role: alerter
+    tools: [Read, WebFetch]
+    reads: ["workspace/analysis/"]
+    writes: ["workspace/alerts/"]
+    description: "Sends alerts to configured interfaces"
+  }
+
+  flow {
+    collector -> [analyzer]
+    analyzer -> reporter     [when analyzer.severity == info]
+    analyzer -> reporter     [when analyzer.severity == warning]
+    analyzer -> [reporter, alerter] [when analyzer.severity == critical]
+  }
+
+  gates {
+    gate metric-validation {
+      after: collector
+      before: analyzer
+      run: "scripts/validate-metrics.sh"
+      checks: [format, completeness]
+      on-fail: bounce-back
+    }
+  }
+
+  memory {
+    workspace {
+      path: ".monitor/workspace/"
+      structure: [metrics, analysis, reports, alerts]
+    }
+  }
+
+  triggers {
+    command monitor {
+      pattern: "/monitor"
+    }
+    command report {
+      pattern: "/report <TICKET>"
+      argument: TICKET
+    }
+  }
+
+  # First-class schedule — replaces extensions.openclaw.cron-jobs
+  schedule {
+    job health-check {
+      cron: "*/15 * * * *"
+      agent: collector
+    }
+    job daily-report {
+      cron: "0 9 * * *"
+      agent: reporter
+    }
+    job weekly-deep-scan {
+      every: "monday 3:00"
+      agent: analyzer
+      enabled: true
+    }
+  }
+
+  # First-class interfaces — replaces extensions.openclaw.channels
+  interfaces {
+    slack {
+      type: webhook
+      webhook: "${SLACK_MONITORING_WEBHOOK}"
+      channel: "ops-alerts"
+    }
+    pagerduty {
+      type: http
+      webhook: "${PAGERDUTY_WEBHOOK_URL}"
+      auth: "${PAGERDUTY_API_KEY}"
+    }
+    dashboard {
+      type: http
+      port: 3000
+    }
+  }
+
+  settings {
+    allow: [Read, Write, Bash, WebFetch, Grep]
+    deny: [Edit]
+    # First-class sandbox — topology-wide default
+    sandbox: docker
+    # First-class fallback chain — topology-wide default
+    fallback-chain: [opus, sonnet, haiku]
+  }
+
+  providers {
+    anthropic {
+      api-key: "${ANTHROPIC_API_KEY}"
+      models: [opus, sonnet, haiku]
+      default: true
+    }
+  }
+
+  hooks {
+    hook alert-on-error {
+      on: Error
+      run: "scripts/alert-on-error.sh"
+      type: command
+    }
+  }
+
+  metering {
+    track: [tokens-in, tokens-out, cost, wall-time]
+    per: [agent, topology]
+    output: "metrics.jsonl"
+    format: jsonl
+    pricing: anthropic-current
+  }
+}

package/examples/simple-pipeline.at

@@ -0,0 +1,163 @@
+# simple-pipeline.at — A basic 3-agent content pipeline
+#
+# Demonstrates: pipeline pattern, basic flow, gate, roles, triggers
+
+topology simple-pipeline : [pipeline, human-gate] {
+
+  meta {
+    version: "1.0.0"
+    description: "Research, write, and review — a minimal content pipeline"
+  }
+
+  providers {
+    anthropic {
+      api-key: "${ANTHROPIC_API_KEY}"
+      models: [opus, sonnet, haiku]
+      default: true
+    }
+  }
+
+  orchestrator {
+    model: sonnet
+    generates: "commands/create.md"
+    handles: [intake, done]
+    outputs: {
+      topic-type: technical | creative
+    }
+  }
+
+  roles {
+    researcher: "Gather information, find sources, and compile research notes"
+    writer: "Draft content based on research, following style guidelines"
+    reviewer: "Review drafts for accuracy, clarity, and completeness"
+  }
+
+  # --- Actions ---
+
+  action intake {
+    kind: inline
+    description: "Parse user request — extract topic and requirements"
+  }
+
+  # --- Agents ---
+
+  agent researcher {
+    role: researcher
+    model: sonnet
+    permissions: supervised
+    phase: 1
+    tools: [Read, Grep, Glob, WebSearch]
+    writes: ["workspace/research.md"]
+
+    prompt {
+        You are a research specialist focused on gathering comprehensive information.
+
+        ## Guidelines
+        - Search broadly for relevant sources
+        - Compile findings into structured research notes
+        - Include citations and source URLs
+        - Prioritize recent and authoritative sources
+    }
+  }
+
+  agent writer {
+    role: writer
+    model: sonnet
+    permissions: autonomous
+    phase: 2
+    tools: [Read, Write, Glob]
+    reads: ["workspace/research.md"]
+    writes: ["workspace/draft.md"]
+    outputs: {
+      confidence: high | medium | low
+    }
+
+    prompt {
+        You are a content writer who transforms research into polished drafts.
+
+        ## Guidelines
+        - Follow the style guide and tone requirements
+        - Structure content with clear headings and sections
+        - Incorporate all key findings from the research
+        - Write for the target audience specified in the brief
+    }
+  }
+
+  agent reviewer {
+    role: reviewer
+    model: opus
+    permissions: supervised
+    phase: 3
+    tools: [Read, Grep, Glob]
+    reads: ["workspace/draft.md", "workspace/research.md"]
+    writes: ["workspace/review.md"]
+    outputs: {
+      verdict: approve | revise | reject
+    }
+
+    prompt {
+        You are a content reviewer ensuring quality and accuracy.
+
+        ## Guidelines
+        - Verify all claims against the research sources
+        - Check for clarity, grammar, and logical flow
+        - Assess completeness against the original requirements
+        - Provide actionable feedback for revisions if needed
+    }
+  }
+
+  # --- Flow ---
+
+  flow {
+    intake -> researcher
+    researcher -> writer
+    writer -> reviewer
+    reviewer -> writer     [when reviewer.verdict == revise, max 2]
+    reviewer -> researcher [when reviewer.verdict == reject, max 1]
+    reviewer -> done       [when reviewer.verdict == approve]
+  }
+
+  # --- Gates ---
+
+  gates {
+    gate quality-check {
+      after: writer
+      before: reviewer
+      run: "scripts/check-quality.sh"
+      checks: [grammar, formatting]
+      on-fail: bounce-back
+    }
+  }
+
+  # --- Action to finish ---
+
+  action done {
+    kind: report
+    description: "Deliver final content to the user"
+  }
+
+  # --- Memory ---
+
+  memory {
+    workspace {
+      path: "workspace/"
+      structure: [research, drafts, reviews]
+    }
+  }
+
+  # --- Triggers ---
+
+  triggers {
+    command create {
+      pattern: "/create <TOPIC>"
+      argument: TOPIC
+    }
+  }
+
+  # --- Settings ---
+
+  settings {
+    allow: ["Read", "Grep", "Glob", "WebSearch"]
+    deny: ["Bash(rm -rf *)"]
+  }
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "agentopology",
+  "version": "0.1.0",
+  "description": "The declarative language for multi-agent systems. Write once, scaffold for any platform.",
+  "author": "Nadav Naveh",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "agentopology": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "spec",
+    "examples",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./parser": {
+      "import": "./dist/parser/index.js",
+      "types": "./dist/parser/index.d.ts"
+    },
+    "./bindings": {
+      "import": "./dist/bindings/index.js",
+      "types": "./dist/bindings/index.d.ts"
+    },
+    "./visualizer": {
+      "import": "./dist/visualizer/index.js",
+      "types": "./dist/visualizer/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "agents",
+    "multi-agent",
+    "topology",
+    "orchestration",
+    "ai",
+    "llm",
+    "claude",
+    "codex",
+    "gemini",
+    "declarative",
+    "scaffold"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentopology/agentopology.git"
+  },
+  "homepage": "https://github.com/agentopology/agentopology",
+  "bugs": {
+    "url": "https://github.com/agentopology/agentopology/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "dagre": "^0.8.5"
+  },
+  "devDependencies": {
+    "ai": "^6.0.116",
+    "tsx": "^4.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}