agent-operating-substrate 0.1.0__py3-none-any.whl

aos/blackboard.py

@@ -0,0 +1,114 @@
+"""Asynchronous local blackboard event bus for peer-to-peer agent coordination."""
+
+from __future__ import annotations
+import json
+import time
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterator, Optional
+
+
+@dataclass
+class BlackboardEvent:
+    type: str
+    sender: str
+    payload: dict[str, Any] = field(default_factory=dict)
+    event_id: str = ""
+    timestamp: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.event_id:
+            prefix = int(time.time() * 1000)
+            short_id = uuid.uuid4().hex[:6]
+            self.event_id = f"evt-{prefix}-{short_id}"
+        if not self.timestamp:
+            self.timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "event_id": self.event_id,
+            "timestamp": self.timestamp,
+            "type": self.type,
+            "sender": self.sender,
+            "payload": self.payload,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> BlackboardEvent:
+        return cls(
+            event_id=str(data.get("event_id", "")),
+            timestamp=str(data.get("timestamp", "")),
+            type=str(data.get("type", "")),
+            sender=str(data.get("sender", "")),
+            payload=dict(data.get("payload", {})),
+        )
+
+
+def get_default_event_log(root_dir: Path | str = ".") -> Path:
+    """Resolve path to default events.jsonl ledger."""
+    root = Path(root_dir)
+    return root / ".agents" / "blackboard" / "events.jsonl"
+
+
+def post_event(
+    event: BlackboardEvent | dict[str, Any],
+    event_log_path: Optional[Path | str] = None,
+    root_dir: Path | str = ".",
+) -> BlackboardEvent:
+    """Append an event to the local blackboard ledger."""
+    if isinstance(event, dict):
+        event_obj = BlackboardEvent.from_dict(event)
+        # Ensure event_id and timestamp are populated
+        if not event_obj.event_id or not event_obj.timestamp:
+            event_obj = BlackboardEvent(
+                type=event.get("type", "UNKNOWN"),
+                sender=event.get("sender", "anonymous"),
+                payload=event.get("payload", {}),
+                event_id=event.get("event_id", ""),
+                timestamp=event.get("timestamp", ""),
+            )
+    else:
+        event_obj = event
+
+    target_path = Path(event_log_path) if event_log_path else get_default_event_log(root_dir)
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+
+    line = json.dumps(event_obj.to_dict(), separators=(",", ":"))
+    with open(target_path, "a", encoding="utf-8") as f:
+        f.write(line + "\n")
+
+    return event_obj
+
+
+def read_events(
+    event_log_path: Optional[Path | str] = None,
+    event_type: Optional[str] = None,
+    sender: Optional[str] = None,
+    root_dir: Path | str = ".",
+) -> list[BlackboardEvent]:
+    """Read all events from the ledger matching optional filters."""
+    target_path = Path(event_log_path) if event_log_path else get_default_event_log(root_dir)
+    if not target_path.is_file():
+        return []
+
+    events: list[BlackboardEvent] = []
+    with open(target_path, "r", encoding="utf-8") as f:
+        for line in f:
+            stripped = line.strip()
+            if not stripped:
+                continue
+            try:
+                data = json.loads(stripped)
+                ev = BlackboardEvent.from_dict(data)
+                if event_type is not None and ev.type != event_type:
+                    continue
+                if sender is not None and ev.sender != sender:
+                    continue
+                events.append(ev)
+            except Exception:
+                # Ignore corrupted lines to prevent ledger read halts
+                continue
+
+    return events

aos/ci.py

@@ -0,0 +1,201 @@
+"""CI/CD integration engine for GitHub Actions and GitLab pipelines."""
+
+from __future__ import annotations
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from aos.enforcer import Violation, enforce_all
+from aos.harness import sync_harnesses
+
+
+@dataclass
+class CIReport:
+    checked_files: list[str]
+    violations: list[Violation]
+    status: str
+
+    def to_markdown(self) -> str:
+        lines = [
+            "## AOS Invariant Verification Report",
+            "",
+            f"**Status**: {'PASSED' if self.status == 'passed' else 'FAILED'}",
+            f"**Files Evaluated**: {len(self.checked_files)}",
+            f"**Violations Detected**: {len(self.violations)}",
+            "",
+        ]
+        if not self.violations:
+            lines.append("All modified files strictly comply with active substrate invariants.")
+        else:
+            lines.append("### Invariant Violations")
+            for v in self.violations:
+                loc = f":{v.line_number}" if v.line_number else ""
+                lines.append(f"* **[{v.rule_id}]** `{v.file_path}{loc}`: {v.message} (`{v.enforcement}`)")
+        lines.append("")
+        return "\n".join(lines)
+
+
+def get_git_changed_files(base_ref: str = "origin/main", root_dir: Path | str = ".") -> list[str]:
+    """Retrieve list of files changed relative to base ref."""
+    root = Path(root_dir)
+    try:
+        res = subprocess.run(
+            ["git", "diff", "--name-only", "--diff-filter=ACM", f"{base_ref}...HEAD"],
+            cwd=str(root),
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return [f.strip() for f in res.stdout.splitlines() if f.strip()]
+    except Exception:
+        # Fallback to local staged or modified files
+        try:
+            res = subprocess.run(
+                ["git", "diff", "--name-only", "--diff-filter=ACM", "HEAD"],
+                cwd=str(root),
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            return [f.strip() for f in res.stdout.splitlines() if f.strip()]
+        except Exception:
+            return []
+
+
+def run_ci_check(
+    files: Optional[list[str]] = None,
+    base_ref: str = "origin/main",
+    auto_sync: bool = False,
+    root_dir: Path | str = ".",
+) -> CIReport:
+    """Run comprehensive CI check, sync harnesses if requested, and write step summary."""
+    root = Path(root_dir)
+    target_files = files if files else get_git_changed_files(base_ref=base_ref, root_dir=root)
+
+    if auto_sync:
+        sync_harnesses(root_dir=root)
+
+    violations = enforce_all(target_files, root_dir=root)
+    reject_violations = [v for v in violations if v.enforcement == "reject_diff"]
+
+    status = "failed" if reject_violations else "passed"
+    report = CIReport(
+        checked_files=target_files,
+        violations=violations,
+        status=status,
+    )
+
+    # Write to GITHUB_STEP_SUMMARY if available
+    summary_path = os.getenv("GITHUB_STEP_SUMMARY")
+    if summary_path:
+        try:
+            with open(summary_path, "a", encoding="utf-8") as f:
+                f.write(report.to_markdown() + "\n")
+        except Exception:
+            pass
+
+    return report
+
+
+def review_pr_diff(diff_content: str, root_dir: Path | str = ".") -> dict[str, Any]:
+    """Analyze unified git diff, evaluate against active invariants, and format PR review comments."""
+    from aos.engine import RuleEngine
+    from aos.enforcer import check_content_violations
+    from aos.harness import get_rule_guidance
+
+    root = Path(root_dir)
+    engine = RuleEngine(root_dir=root)
+    comments: list[dict[str, Any]] = []
+    current_file: Optional[str] = None
+    file_lines: list[str] = []
+
+    def evaluate_file(file_path: str, lines: list[str]) -> None:
+        content = "\n".join(lines)
+        matched = engine.match_file(file_path, status="active")
+        violations = check_content_violations(file_path, content, matched)
+        for v in violations:
+            rule_obj = next((r for r in matched if r.id == v.rule_id), None)
+            compliant = get_rule_guidance(rule_obj)[0] if rule_obj else None
+            sugg = f"\n\n**Compliant Pattern**: `{compliant}`" if compliant else ""
+            comments.append({
+                "file_path": v.file_path,
+                "line_number": v.line_number or 1,
+                "rule_id": v.rule_id,
+                "message": v.message,
+                "comment_body": f"### Invariant Barrier [{v.rule_id}]\n\n{v.message}{sugg}",
+            })
+
+    for line in diff_content.splitlines():
+        if line.startswith("+++ b/"):
+            if current_file and file_lines:
+                evaluate_file(current_file, file_lines)
+            current_file = line[6:].strip()
+            file_lines = []
+        elif current_file and line.startswith("+") and not line.startswith("+++"):
+            file_lines.append(line[1:])
+
+    if current_file and file_lines:
+        evaluate_file(current_file, file_lines)
+
+    return {
+        "status": "changes_requested" if comments else "approved",
+        "comments_count": len(comments),
+        "comments": comments,
+    }
+
+
+DEFAULT_GITHUB_WORKFLOW = """name: AOS Guardrails
+
+on:
+  pull_request:
+    branches: [ master, main ]
+  push:
+    branches: [ master, main ]
+
+jobs:
+  verify-invariants:
+    name: Verify Substrate Invariants
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install AOS
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+
+      - name: Verify Invariants
+        run: |
+          python -m aos ci run --auto-sync
+"""
+
+
+def install_ci_workflow(root_dir: Path | str = ".") -> Path:
+    """Install GitHub Actions workflow in .github/workflows/aos-guardrails.yml."""
+    root = Path(root_dir)
+    wf_dir = root / ".github" / "workflows"
+    wf_dir.mkdir(parents=True, exist_ok=True)
+    target = wf_dir / "aos-guardrails.yml"
+    target.write_text(DEFAULT_GITHUB_WORKFLOW, encoding="utf-8")
+    return target
+
+
+def uninstall_ci_workflow(root_dir: Path | str = ".") -> bool:
+    """Remove GitHub Actions workflow if installed."""
+    target = Path(root_dir) / ".github" / "workflows" / "aos-guardrails.yml"
+    if target.is_file():
+        target.unlink()
+        return True
+    return False
+