asfops 0.1.0__py3-none-any.whl

asfops/__init__.py

@@ -0,0 +1,83 @@
+"""asfops — Agentic Security Fleet Ops.
+
+A security department of LLM agents: a Security Orchestrator triages any
+assessment request, fans out to the relevant fleet members, and composes a
+single comprehensive markdown report with optional usage metadata.
+
+Quickstart::
+
+    import asfops
+
+    result = asfops.assess_sync("Review our new file-upload API design")
+    print(result.report_md)
+"""
+
+from asfops._version import __version__
+from asfops.api import (
+    Fleet,
+    assess,
+    assess_sync,
+    compose_report,
+    list_roles,
+)
+from asfops.config import FleetConfig
+from asfops.exceptions import (
+    AsfopsError,
+    CopilotRuntimeError,
+    RoleNotFoundError,
+    ToolsNotSupportedError,
+    TriageError,
+)
+from asfops.fleet.roles import REGISTRY, RoleRegistry, RoleSpec
+from asfops.fleet.schemas import (
+    AgentReport,
+    Finding,
+    RoleSelection,
+    Severity,
+    SynthesisSummary,
+    TriageDecision,
+)
+from asfops.models import CopilotBridge, CopilotModel, ModelRef, resolve_model, shutdown
+from asfops.results import (
+    AgentResult,
+    AgentUsage,
+    FleetEvent,
+    FleetMetadata,
+    FleetResult,
+    ModelUsageTotals,
+)
+
+__all__ = [
+    "REGISTRY",
+    "AgentReport",
+    "AgentResult",
+    "AgentUsage",
+    "AsfopsError",
+    "CopilotBridge",
+    "CopilotModel",
+    "CopilotRuntimeError",
+    "Finding",
+    "Fleet",
+    "FleetConfig",
+    "FleetEvent",
+    "FleetMetadata",
+    "FleetResult",
+    "ModelRef",
+    "ModelUsageTotals",
+    "RoleNotFoundError",
+    "RoleRegistry",
+    "RoleSelection",
+    "RoleSpec",
+    "Severity",
+    "SynthesisSummary",
+    "ToolsNotSupportedError",
+    "TriageDecision",
+    "TriageError",
+    "__version__",
+    "assess",
+    "assess_sync",
+    "compose_report",
+    "list_roles",
+    "resolve_model",
+    "shutdown",
+]

asfops/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

asfops/api.py

@@ -0,0 +1,128 @@
+"""The public asfops API: the Fleet and module-level conveniences.
+
+Designed as the interface an LLM tool-caller would want: one free-text
+entrypoint (:meth:`Fleet.assess`), a discoverable roster
+(:func:`list_roles`), a targeted single-expert call (:meth:`Fleet.run_role`),
+and a fully ``model_dump_json()``-able :class:`~asfops.results.FleetResult`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import UTC, datetime
+
+from asfops.config import FleetConfig
+from asfops.fleet.roles import REGISTRY, RoleRegistry, RoleSpec
+from asfops.fleet.schemas import RoleSelection, TriageDecision
+from asfops.models.client import shutdown
+from asfops.orchestrator import EventCallback, Orchestrator
+from asfops.results import (
+    AgentResult,
+    FleetMetadata,
+    FleetResult,
+    aggregate_usage,
+    build_report_md,
+)
+
+
+class Fleet:
+    """The security fleet: triage, invoke specialists, synthesize a report."""
+
+    def __init__(
+        self, config: FleetConfig | None = None, *, registry: RoleRegistry | None = None
+    ) -> None:
+        self.config = config or FleetConfig()
+        self.registry = registry or REGISTRY
+        self._orchestrator = Orchestrator(self.config, registry=self.registry)
+
+    async def assess(self, request: str, *, on_event: EventCallback | None = None) -> FleetResult:
+        """Run a full assessment: triage → fan-out → synthesis → report."""
+        return await self._orchestrator.run(request, on_event=on_event)
+
+    def assess_sync(self, request: str, *, on_event: EventCallback | None = None) -> FleetResult:
+        """Synchronous wrapper around :meth:`assess`.
+
+        Raises if called from within a running event loop (e.g. Jupyter);
+        ``await fleet.assess(...)`` there instead.
+        """
+        _guard_no_running_loop()
+        return asyncio.run(self.assess(request, on_event=on_event))
+
+    async def run_role(self, slug: str, request: str) -> AgentResult:
+        """Engage a single specialist by slug (no triage, no synthesis)."""
+        self.registry.get(slug)  # validates slug, raises RoleNotFoundError
+        sel = RoleSelection(slug=slug, rationale="Directly requested.", priority="primary")
+        return await self._orchestrator._run_role(sel, request, on_event=None)
+
+    def run_role_sync(self, slug: str, request: str) -> AgentResult:
+        _guard_no_running_loop()
+        return asyncio.run(self.run_role(slug, request))
+
+    def roster(self) -> tuple[RoleSpec, ...]:
+        """The specialists available to this fleet."""
+        return self.registry.all()
+
+    async def aclose(self) -> None:
+        """Shut down the shared Copilot runtime, if one was started."""
+        await shutdown()
+
+
+def _guard_no_running_loop() -> None:
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return
+    raise RuntimeError(
+        "assess_sync() cannot be called from a running event loop; "
+        "use `await fleet.assess(...)` instead."
+    )
+
+
+async def assess(request: str, *, config: FleetConfig | None = None) -> FleetResult:
+    """Assess a request with a default (or supplied) fleet configuration."""
+    return await Fleet(config).assess(request)
+
+
+def assess_sync(request: str, *, config: FleetConfig | None = None) -> FleetResult:
+    """Synchronous convenience wrapper around :func:`assess`."""
+    return Fleet(config).assess_sync(request)
+
+
+def list_roles(*, registry: RoleRegistry | None = None) -> tuple[RoleSpec, ...]:
+    """The full security-department roster."""
+    return (registry or REGISTRY).all()
+
+
+def compose_report(
+    request: str,
+    triage: TriageDecision,
+    agent_results: list[AgentResult],
+    *,
+    include_metadata: bool = True,
+) -> FleetResult:
+    """Assemble a :class:`FleetResult` from pre-computed pieces (no synthesis).
+
+    Useful when a caller has already run roles and just wants the composed
+    markdown report and usage rollup.
+    """
+    now = datetime.now(UTC)
+    metadata: FleetMetadata | None = None
+    if include_metadata:
+        per_agent = [r.usage for r in agent_results]
+        totals, grand = aggregate_usage(per_agent)
+        metadata = FleetMetadata(
+            per_agent=per_agent,
+            totals_by_model=totals,
+            grand_total=grand,
+            started_at=now,
+            finished_at=now,
+        )
+    report_md = build_report_md(request, triage, agent_results, None, metadata)
+    return FleetResult(
+        request=request,
+        triage=triage,
+        agent_results=agent_results,
+        synthesis=None,
+        report_md=report_md,
+        metadata=metadata,
+    )

asfops/cli/__init__.py

@@ -0,0 +1,5 @@
+"""asfops command-line interface."""
+
+from asfops.cli.app import app, main
+
+__all__ = ["app", "main"]

asfops/cli/app.py

@@ -0,0 +1,282 @@
+"""The asfops command-line interface (typer + rich)."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.markdown import Markdown
+
+from asfops._version import __version__
+from asfops.api import Fleet
+from asfops.cli.render import ProgressReporter, metadata_table, roster_table
+from asfops.config import FleetConfig
+from asfops.exceptions import AsfopsError, RoleNotFoundError
+from asfops.results import AgentResult, FleetResult, build_agent_report_md
+
+app = typer.Typer(
+    name="asfops",
+    help="Agentic Security Fleet Ops — a security department of LLM agents.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+_stdout = Console()
+_stderr = Console(stderr=True)
+
+
+class OutputFormat(StrEnum):
+    md = "md"
+    json = "json"
+
+
+class RosterFormat(StrEnum):
+    table = "table"
+    json = "json"
+
+
+def _read_request(request: str | None, file: Path | None) -> str:
+    if file is not None:
+        return file.read_text(encoding="utf-8")
+    if request in (None, "-"):
+        data = sys.stdin.read()
+        if not data.strip():
+            _fail("No request provided (empty stdin).")
+        return data
+    assert request is not None
+    return request
+
+
+def _fail(message: str, code: int = 1) -> None:
+    _stderr.print(f"[red]error:[/red] {message}")
+    raise typer.Exit(code)
+
+
+async def _assess_and_close(fleet: Fleet, text: str, reporter: object) -> FleetResult:
+    # Run the assessment and shut the shared Copilot client down inside the SAME
+    # event loop — stopping it from a second asyncio.run() fails (loop closed).
+    try:
+        return await fleet.assess(text, on_event=reporter)  # type: ignore[arg-type]
+    finally:
+        await fleet.aclose()
+
+
+async def _run_role_and_close(fleet: Fleet, slug: str, text: str) -> AgentResult:
+    try:
+        return await fleet.run_role(slug, text)
+    finally:
+        await fleet.aclose()
+
+
+def _build_config(
+    model: str | None,
+    triage_model: str | None,
+    roles: list[str] | None,
+    exclude: list[str] | None,
+    concurrency: int | None,
+    timeout: float | None,
+    no_metadata: bool,
+) -> FleetConfig:
+    cfg = FleetConfig()
+    if model:
+        cfg.default_model = model
+    if triage_model:
+        cfg.triage_model = triage_model
+    if roles:
+        cfg.force_roles = tuple(roles)
+    if exclude:
+        cfg.exclude_roles = tuple(exclude)
+    if concurrency:
+        cfg.max_concurrency = concurrency
+    if timeout:
+        cfg.per_agent_timeout_s = timeout
+    cfg.include_metadata = not no_metadata
+    return cfg
+
+
+@app.command()
+def assess(
+    request: Annotated[
+        str | None, typer.Argument(help="The assessment request text, or '-' for stdin.")
+    ] = None,
+    file: Annotated[
+        Path | None, typer.Option("--file", "-f", help="Read the request from a file.")
+    ] = None,
+    model: Annotated[
+        str | None, typer.Option("--model", "-m", help="Default model ref for all agents.")
+    ] = None,
+    triage_model: Annotated[
+        str | None, typer.Option("--triage-model", help="Model ref for the triage step.")
+    ] = None,
+    role: Annotated[
+        list[str] | None, typer.Option("--role", "-r", help="Force a role (repeatable).")
+    ] = None,
+    exclude: Annotated[
+        list[str] | None, typer.Option("--exclude", "-x", help="Exclude a role (repeatable).")
+    ] = None,
+    concurrency: Annotated[
+        int | None, typer.Option("--concurrency", "-c", help="Max concurrent agents.")
+    ] = None,
+    timeout: Annotated[
+        float | None, typer.Option("--timeout", help="Per-agent timeout (seconds).")
+    ] = None,
+    output_format: Annotated[
+        OutputFormat, typer.Option("--format", help="Output format.")
+    ] = OutputFormat.md,
+    output: Annotated[
+        Path | None, typer.Option("--output", "-o", help="Write output to a file.")
+    ] = None,
+    no_metadata: Annotated[
+        bool, typer.Option("--no-metadata", help="Omit usage metadata.")
+    ] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress progress output.")] = False,
+) -> None:
+    """Run a full fleet assessment and print the composed report."""
+    text = _read_request(request, file)
+    cfg = _build_config(model, triage_model, role, exclude, concurrency, timeout, no_metadata)
+    fleet = Fleet(cfg)
+
+    show_progress = not quiet and output_format is OutputFormat.md and output is None
+    reporter = ProgressReporter(_stderr) if show_progress else None
+
+    try:
+        result = asyncio.run(_assess_and_close(fleet, text, reporter))
+    except AsfopsError as exc:
+        _fail(str(exc))
+        return
+
+    if output_format is OutputFormat.json:
+        payload = result.model_dump_json(indent=2)
+        _emit(payload, output)
+        return
+
+    if output is not None:
+        _emit(result.report_md, output)
+        return
+
+    _stdout.print(Markdown(result.report_md))
+    table = metadata_table(result)
+    if table is not None and not no_metadata:
+        _stdout.print(table)
+
+
+@app.command()
+def run(
+    slug: Annotated[str, typer.Argument(help="Role slug to engage (see `asfops roster`).")],
+    request: Annotated[
+        str | None, typer.Argument(help="The request text, or '-' for stdin.")
+    ] = None,
+    file: Annotated[Path | None, typer.Option("--file", "-f")] = None,
+    model: Annotated[str | None, typer.Option("--model", "-m")] = None,
+    output_format: Annotated[
+        OutputFormat, typer.Option("--format", help="Output format.")
+    ] = OutputFormat.md,
+) -> None:
+    """Engage a single specialist directly (no triage, no synthesis)."""
+    text = _read_request(request, file)
+    cfg = FleetConfig()
+    if model:
+        cfg.default_model = model
+    fleet = Fleet(cfg)
+    try:
+        result = asyncio.run(_run_role_and_close(fleet, slug, text))
+    except RoleNotFoundError as exc:
+        _fail(str(exc), code=2)
+        return
+    except AsfopsError as exc:
+        _fail(str(exc))
+        return
+
+    if output_format is OutputFormat.json:
+        _stdout.print_json(result.model_dump_json())
+        return
+    if result.report is None:
+        _fail(f"{slug} failed: {result.error}")
+        return
+    _stdout.print(Markdown(build_agent_report_md(result.role_name, result.report)))
+
+
+@app.command()
+def roster(
+    output_format: Annotated[
+        RosterFormat, typer.Option("--format", help="Output format.")
+    ] = RosterFormat.table,
+) -> None:
+    """List the security specialists in the fleet."""
+    roles = Fleet().roster()
+    if output_format is RosterFormat.json:
+        import json
+
+        _stdout.print_json(
+            json.dumps(
+                [
+                    {"slug": r.slug, "name": r.name, "charter": r.charter, "tags": list(r.tags)}
+                    for r in roles
+                ]
+            )
+        )
+        return
+    _stdout.print(roster_table(roles))
+
+
+@app.command()
+def models() -> None:
+    """Check GitHub Copilot availability and list available models."""
+    try:
+        from copilot import CopilotClient
+    except ImportError:
+        _fail("github-copilot-sdk is not installed.")
+        return
+
+    async def _list() -> list[str]:
+        client = CopilotClient(log_level="error")
+        await client.start()
+        try:
+            infos = await client.list_models()
+            return [getattr(m, "id", str(m)) for m in infos]
+        finally:
+            await client.stop()
+
+    try:
+        ids = asyncio.run(_list())
+    except Exception as exc:
+        _stderr.print(f"[yellow]Copilot runtime unavailable:[/yellow] {exc}")
+        _stdout.print(
+            "You can still run the fleet on any pydantic-ai model, e.g. "
+            "[cyan]--model openai:gpt-5.2[/cyan] or "
+            "[cyan]--model anthropic:claude-sonnet-4-5[/cyan]."
+        )
+        raise typer.Exit(0) from None
+    _stdout.print("[green]Copilot runtime OK.[/green] Available models:")
+    for mid in ids:
+        _stdout.print(f"  • copilot:{mid}")
+
+
+@app.command()
+def version() -> None:
+    """Print the asfops version."""
+    _stdout.print(__version__)
+
+
+def _emit(content: str, output: Path | None) -> None:
+    if output is not None:
+        output.write_text(content, encoding="utf-8")
+        _stderr.print(f"[green]Wrote[/green] {output}")
+    else:
+        # plain stdout, no rich formatting (pipe-friendly)
+        sys.stdout.write(content)
+        if not content.endswith("\n"):
+            sys.stdout.write("\n")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

asfops/cli/render.py

@@ -0,0 +1,76 @@
+"""Rich rendering helpers for the CLI."""
+
+from __future__ import annotations
+
+import threading
+
+from rich.console import Console
+from rich.table import Table
+
+from asfops.fleet.roles import RoleSpec
+from asfops.results import FleetEvent, FleetResult
+
+
+def roster_table(roles: tuple[RoleSpec, ...]) -> Table:
+    table = Table(title="Security Fleet Roster", show_lines=False, expand=True)
+    table.add_column("Slug", style="cyan", no_wrap=True)
+    table.add_column("Role", style="bold")
+    table.add_column("Charter")
+    for role in roles:
+        table.add_row(role.slug, role.name, role.charter)
+    return table
+
+
+def metadata_table(result: FleetResult) -> Table | None:
+    if result.metadata is None:
+        return None
+    table = Table(title="Usage by Model", expand=True)
+    table.add_column("Model", style="cyan")
+    table.add_column("Requests", justify="right")
+    table.add_column("Input", justify="right")
+    table.add_column("Output", justify="right")
+    for t in result.metadata.totals_by_model:
+        table.add_row(t.model_id, str(t.requests), str(t.input_tokens), str(t.output_tokens))
+    g = result.metadata.grand_total
+    table.add_row(
+        "[bold]all[/bold]",
+        f"[bold]{g.requests}[/bold]",
+        f"[bold]{g.input_tokens}[/bold]",
+        f"[bold]{g.output_tokens}[/bold]",
+    )
+    return table
+
+
+class ProgressReporter:
+    """Renders live per-role progress from fleet events.
+
+    Kept deliberately simple (line-based, thread-safe) so it composes with any
+    console and needs no live-refresh teardown.
+    """
+
+    def __init__(self, console: Console) -> None:
+        self.console = console
+        self._lock = threading.Lock()
+
+    def __call__(self, event: FleetEvent) -> None:
+        with self._lock:
+            self._render(event)
+
+    def _render(self, event: FleetEvent) -> None:
+        c = self.console
+        match event.kind:
+            case "triage_started":
+                c.print("[dim]Triaging request…[/dim]")
+            case "triage_finished":
+                c.print(f"[green]Triage selected:[/green] {event.detail}")
+            case "agent_started":
+                c.print(f"  [yellow]▶ {event.slug}[/yellow] running…")
+            case "agent_finished":
+                c.print(f"  [green]✓ {event.slug}[/green] done")
+            case "agent_failed":
+                c.print(f"  [red]✗ {event.slug}[/red] failed: {event.detail}")
+            case "synthesis_started":
+                c.print("[dim]Synthesizing report…[/dim]")
+            case "synthesis_finished":
+                detail = f" ({event.detail})" if event.detail else ""
+                c.print(f"[green]Synthesis complete[/green]{detail}")

asfops/config.py

@@ -0,0 +1,56 @@
+"""Fleet configuration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from asfops.models.resolve import ModelRef
+
+CopilotMode = Literal["model", "bridge"]
+
+DEFAULT_MODEL: ModelRef = "copilot:claude-sonnet-4.5"
+DEFAULT_TRIAGE_FALLBACK: tuple[str, ...] = ("security-architect", "threat-model", "appsec")
+
+
+@dataclass
+class FleetConfig:
+    """Configuration for a :class:`~asfops.api.Fleet` run.
+
+    Any :class:`~asfops.models.resolve.ModelRef` is accepted for a model: a
+    ``"copilot:<name>"`` string, a native pydantic-ai model string
+    (``"openai:gpt-5.2"``, ``"anthropic:claude-sonnet-4-5"``, ``"test"``), or a
+    ``Model`` instance.
+    """
+
+    default_model: ModelRef = DEFAULT_MODEL
+    triage_model: ModelRef | None = None
+    """Model used for triage; falls back to ``default_model``."""
+    synthesis_model: ModelRef | None = None
+    """Model used for synthesis; falls back to ``default_model``."""
+    model_overrides: dict[str, ModelRef] = field(default_factory=dict)
+    """Per-role-slug model overrides."""
+
+    max_concurrency: int = 5
+    per_agent_timeout_s: float = 300.0
+
+    force_roles: tuple[str, ...] = ()
+    """Roles always engaged, regardless of triage."""
+    exclude_roles: tuple[str, ...] = ()
+    """Roles never engaged, even if triage or force selects them."""
+
+    include_metadata: bool = True
+    copilot_mode: CopilotMode = "model"
+    """Reserved: ``"bridge"`` routes Copilot agents through the manual bridge."""
+
+    on_empty_triage: Literal["fallback", "error"] = "fallback"
+    """When triage selects nothing usable: engage a default core set, or raise."""
+
+    def triage_model_ref(self) -> ModelRef:
+        return self.triage_model if self.triage_model is not None else self.default_model
+
+    def synthesis_model_ref(self) -> ModelRef:
+        return self.synthesis_model if self.synthesis_model is not None else self.default_model
+
+    def model_for_role(self, slug: str) -> ModelRef:
+        return self.model_overrides.get(slug, self.default_model)

asfops/exceptions.py

@@ -0,0 +1,33 @@
+"""Exception hierarchy for asfops."""
+
+from __future__ import annotations
+
+
+class AsfopsError(Exception):
+    """Base class for all asfops errors."""
+
+
+class CopilotRuntimeError(AsfopsError):
+    """The Copilot runtime failed to start, respond, or complete a turn."""
+
+
+class ToolsNotSupportedError(AsfopsError):
+    """Raised when pydantic-ai function tools are requested on a CopilotModel.
+
+    The Copilot runtime executes tools inside its own turn and cannot return
+    tool calls to pydantic-ai. Use an API-key model (e.g. ``openai:...`` or
+    ``anthropic:...``) for agents that need custom tools.
+    """
+
+
+class RoleNotFoundError(AsfopsError):
+    """Raised when a role slug is not present in the registry."""
+
+    def __init__(self, slug: str, known: tuple[str, ...]) -> None:
+        self.slug = slug
+        self.known = known
+        super().__init__(f"Unknown role slug {slug!r}. Known roles: {', '.join(known)}")
+
+
+class TriageError(AsfopsError):
+    """Raised when triage produces no usable role selection."""

asfops/fleet/__init__.py

@@ -0,0 +1,31 @@
+"""Fleet: security-department roles, schemas, and agent construction."""
+
+from asfops.fleet.member import build_agent
+from asfops.fleet.roles import REGISTRY, RoleRegistry, RoleSpec
+from asfops.fleet.roster import register_default_roles
+from asfops.fleet.schemas import (
+    SEVERITY_ORDER,
+    AgentReport,
+    Confidence,
+    Finding,
+    RoleSelection,
+    Severity,
+    SynthesisSummary,
+    TriageDecision,
+)
+
+__all__ = [
+    "REGISTRY",
+    "SEVERITY_ORDER",
+    "AgentReport",
+    "Confidence",
+    "Finding",
+    "RoleRegistry",
+    "RoleSelection",
+    "RoleSpec",
+    "Severity",
+    "SynthesisSummary",
+    "TriageDecision",
+    "build_agent",
+    "register_default_roles",
+]