ase-python 0.1.0__py3-none-any.whl

ase/config/env_loader.py

@@ -0,0 +1,71 @@
+"""Minimal `.env` loader used to keep CLI startup dependency-free.
+
+ASE only needs project-local environment bootstrapping, not the full feature
+surface of a third-party dotenv package. Keeping this logic in-repo avoids
+startup failures caused by unrelated environment plugins or broken installs.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+from pathlib import Path
+
+from ase.errors import ConfigError
+
+ENV_FILE_NAME = ".env"
+
+
+def load_local_dotenv(start: Path | None = None) -> Path | None:
+    """Load the nearest project `.env` without overriding existing variables."""
+    env_path = _find_dotenv(start or Path.cwd())
+    if env_path is None:
+        return None
+    try:
+        lines = env_path.read_text(encoding="utf-8").splitlines()
+    except OSError as exc:
+        raise ConfigError(f"failed to read env file {env_path}: {exc}") from exc
+    for line in lines:
+        parsed = _parse_env_line(line)
+        if parsed is None:
+            continue
+        key, value = parsed
+        os.environ.setdefault(key, value)
+    return env_path
+
+
+def _find_dotenv(start: Path) -> Path | None:
+    """Search upward so ASE commands work from example and subdirectories."""
+    current = start.resolve()
+    for directory in [current, *current.parents]:
+        candidate = directory / ENV_FILE_NAME
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _parse_env_line(line: str) -> tuple[str, str] | None:
+    """Handle the simple KEY=VALUE syntax ASE documents for local setup."""
+    stripped = line.strip()
+    if not stripped or stripped.startswith("#"):
+        return None
+    if stripped.startswith("export "):
+        stripped = stripped.removeprefix("export ").strip()
+    if "=" not in stripped:
+        return None
+    key, raw_value = stripped.split("=", 1)
+    key = key.strip()
+    value = _normalize_value(raw_value.strip())
+    return (key, value) if key else None
+
+
+def _normalize_value(raw_value: str) -> str:
+    """Preserve quoted values while allowing inline comments on bare values."""
+    if not raw_value:
+        return ""
+    if raw_value[0] in {"'", '"'}:
+        try:
+            return shlex.split(raw_value)[0]
+        except ValueError:
+            return raw_value.strip("'\"")
+    return raw_value.split(" #", 1)[0].strip()

ase/config/loader.py

@@ -0,0 +1,82 @@
+"""Configuration discovery and loading for ASE commands.
+
+The CLI needs one predictable config flow: walk upward for `ase.yaml`, load it
+if present, and otherwise return defaults. Keeping this logic in one module
+avoids every command reimplementing file discovery and error handling.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from ase.config.model import ASEConfig
+from ase.errors import ConfigError
+
+CONFIG_FILE_NAME = "ase.yaml"
+
+
+def find_config_file(start: Path | None = None) -> Path | None:
+    """Search upward so ASE works from nested example and project directories."""
+    current = (start or Path.cwd()).resolve()
+    for directory in [current, *current.parents]:
+        candidate = directory / CONFIG_FILE_NAME
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def load_config(path: Path | None = None) -> ASEConfig:
+    """Return validated config or defaults when no project config exists."""
+    config_path = path or find_config_file()
+    if config_path is None:
+        return ASEConfig()
+    data = _read_config_dict(config_path)
+    config = _validate_config(data, config_path)
+    _load_declared_env_files(config_path, config)
+    return config
+
+
+def _read_config_dict(path: Path) -> dict[str, object]:
+    """Translate YAML into a plain mapping with contextual parse errors."""
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ConfigError(f"failed to read config {path}: {exc}") from exc
+    try:
+        data = yaml.safe_load(raw) or {}
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"failed to parse config {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"invalid config {path}: root must be a mapping")
+    return data
+
+
+def _validate_config(data: dict[str, object], path: Path) -> ASEConfig:
+    """Centralize model validation so config errors stay user-readable."""
+    try:
+        return ASEConfig.model_validate(data)
+    except Exception as exc:
+        raise ConfigError(f"invalid config {path}: {exc}") from exc
+
+
+def _load_declared_env_files(config_path: Path, config: ASEConfig) -> None:
+    """Load configured env files relative to the config directory in order."""
+    from ase.config.env_loader import _parse_env_line
+    base_dir = config_path.parent
+    for relative in config.env_files:
+        env_path = base_dir / relative
+        if not env_path.exists():
+            continue
+        try:
+            lines = env_path.read_text(encoding="utf-8").splitlines()
+        except OSError as exc:
+            raise ConfigError(f"failed to read env file {env_path}: {exc}") from exc
+        for line in lines:
+            parsed = _parse_env_line(line)
+            if parsed is None:
+                continue
+            key, value = parsed
+            import os
+            os.environ[key] = value

ase/config/model.py

@@ -0,0 +1,51 @@
+"""Pydantic models for ASE project configuration and CLI output formats."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class OutputFormat(StrEnum):
+    """Enumerate stable report/output modes shared by ASE CLI commands."""
+
+    TERMINAL = "terminal"
+    JSON = "json"
+    JUNIT = "junit"
+    MARKDOWN = "markdown"
+    OTEL_JSON = "otel-json"
+
+
+class ProxyConfig(BaseModel):
+    """Capture proxy defaults so watch/test can run reproducibly from config."""
+
+    port: int = 0
+    bind_address: str = "127.0.0.1"
+
+
+class CacheConfig(BaseModel):
+    """Describe the on-disk response cache used for deterministic test runs."""
+
+    enabled: bool = True
+    directory: str = ".ase-cache"
+    max_entries: int = 1000
+
+
+class TraceStoreConfig(BaseModel):
+    """Describe where ASE stores local run history and how much to retain."""
+
+    directory: str = ".ase-traces"
+    keep_last: int = 100
+
+
+class ASEConfig(BaseModel):
+    """Define the project-level ASE defaults loaded from `ase.yaml`."""
+
+    version: int = 1
+    output: OutputFormat = OutputFormat.TERMINAL
+    proxy: ProxyConfig = Field(default_factory=ProxyConfig)
+    cache: CacheConfig = Field(default_factory=CacheConfig)
+    traces: TraceStoreConfig = Field(default_factory=TraceStoreConfig)
+    scenario_dirs: list[str] = Field(default_factory=lambda: ["scenarios"])
+    env_files: list[str] = Field(default_factory=list)

ase/conformance/__init__.py

@@ -0,0 +1,7 @@
+"""Source-backed conformance package that composes with recovery overlays."""
+
+from __future__ import annotations
+
+from pkgutil import extend_path
+
+__path__ = extend_path(__path__, __name__)

ase/conformance/matrix.py

@@ -0,0 +1,111 @@
+"""Compatibility matrix helpers built from certification result artifacts."""
+
+from __future__ import annotations
+
+import datetime
+import json
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from ase.conformance.model import ConformanceResult
+from ase.errors import ConformanceError
+
+
+class CompatibilityRow(BaseModel):
+    """One row in the generated compatibility matrix."""
+
+    framework: str
+    language: str
+    adapter_name: str
+    adapter_version: str
+    bundle_family: str
+    certification_level: str
+    bundle_version: str
+    passed: bool
+    generated_at: str
+    source_artifact: str
+
+
+class CertificationArtifact(BaseModel):
+    """One validated certification artifact paired with its source path."""
+
+    path: str
+    result: ConformanceResult
+
+
+def load_results(paths: list[Path]) -> list[CertificationArtifact]:
+    """Load certification results from JSON files and directories."""
+    return [load_result(path) for path in _expand_result_paths(paths)]
+
+
+def load_result(path: Path) -> CertificationArtifact:
+    """Load one certification result artifact from disk."""
+    if not path.exists():
+        raise ConformanceError(f"certification result not found: {path}")
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ConformanceError(f"failed to read certification result {path}: {exc}") from exc
+    try:
+        result = ConformanceResult.model_validate(payload)
+    except Exception as exc:
+        raise ConformanceError(f"failed to validate certification result {path}: {exc}") from exc
+    return CertificationArtifact(path=str(path), result=result)
+
+
+def build_rows(artifacts: list[CertificationArtifact]) -> list[CompatibilityRow]:
+    """Convert certification results into sorted matrix rows."""
+    rows = [
+        CompatibilityRow(
+            framework=artifact.result.framework or "unknown",
+            language=artifact.result.language or "unknown",
+            adapter_name=artifact.result.adapter_name,
+            adapter_version=artifact.result.adapter_version or "unspecified",
+            bundle_family=artifact.result.bundle_family,
+            certification_level=artifact.result.certification_level.value,
+            bundle_version=artifact.result.bundle_version,
+            passed=artifact.result.passed,
+            generated_at=_format_generated_at(artifact.result.generated_at_ms),
+            source_artifact=artifact.path,
+        )
+        for artifact in artifacts
+    ]
+    return sorted(rows, key=lambda row: (row.framework, row.language, row.adapter_name))
+
+
+def to_markdown(rows: list[CompatibilityRow]) -> str:
+    """Render a compatibility matrix as a Markdown table."""
+    header = (
+        "| Framework | Language | Adapter | Adapter Version | Bundle Family | Level | "
+        "Bundle | Status | Generated | Artifact |\n"
+        "|---|---|---|---|---|---|---|---|---|---|"
+    )
+    body = [
+        "| "
+        f"{row.framework} | {row.language} | {row.adapter_name} | {row.adapter_version} | "
+        f"{row.bundle_family} | {row.certification_level} | {row.bundle_version} | "
+        f"{'certified' if row.passed else 'failing'} | {row.generated_at} | {row.source_artifact} |"
+        for row in rows
+    ]
+    return "\n".join([header, *body])
+
+
+def _expand_result_paths(paths: list[Path]) -> list[Path]:
+    """Accept both artifact files and downloaded-artifact directories."""
+    expanded: list[Path] = []
+    for path in paths:
+        if path.is_dir():
+            expanded.extend(sorted(path.rglob("*.cert.json")))
+        else:
+            expanded.append(path)
+    if not expanded:
+        raise ConformanceError("no certification result artifacts found")
+    return expanded
+
+
+def _format_generated_at(ms: float) -> str:
+    """Render artifact generation time as an ISO-like UTC timestamp."""
+    return datetime.datetime.fromtimestamp(ms / 1000, datetime.UTC).strftime(
+        "%Y-%m-%d %H:%M:%SZ"
+    )

ase/conformance/model.py

@@ -0,0 +1,91 @@
+"""Models for ASE adapter conformance manifests and certification output."""
+
+from __future__ import annotations
+
+import time
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+CONFORMANCE_SPEC_VERSION = 1
+
+
+class CertificationLevel(StrEnum):
+    """Define public certification tiers without scenario-model imports."""
+
+    CORE = "core"
+    STATEFUL = "stateful"
+    MULTI_AGENT = "multi_agent"
+    MCP = "mcp"
+    REALTIME = "realtime"
+
+
+class ConformanceCase(BaseModel):
+    """Describe one reusable certification case inside a conformance bundle."""
+
+    case_id: str
+    name: str
+    adapter_events: str
+    scenario: str | None = None
+    required_event_types: list[str] = Field(default_factory=list)
+    required_protocols: list[str] = Field(default_factory=list)
+    minimum_fidelity: dict[str, int] = Field(default_factory=dict)
+    methodology_profiles: list[str] = Field(default_factory=list)
+
+
+class ConformanceManifest(BaseModel):
+    """Describe one language-neutral certification manifest."""
+
+    spec_version: int = CONFORMANCE_SPEC_VERSION
+    manifest_id: str
+    name: str
+    adapter_name: str
+    adapter_version: str | None = None
+    bundle_family: str = "launch"
+    bundle_version: str = "1.0.0"
+    framework: str | None = None
+    language: str | None = None
+    certification_target: CertificationLevel = CertificationLevel.CORE
+    methodology_profiles: list[str] = Field(default_factory=lambda: ["core"])
+    cases: list[ConformanceCase] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ConformanceCheckResult(BaseModel):
+    """Capture one pass/fail check inside a certification run."""
+
+    check_id: str
+    case_id: str
+    passed: bool
+    message: str
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class ConformanceResult(BaseModel):
+    """Represent one certification result emitted by `ase certify`."""
+
+    spec_version: int = CONFORMANCE_SPEC_VERSION
+    manifest_id: str
+    manifest_name: str
+    adapter_name: str
+    adapter_version: str | None = None
+    bundle_family: str = "launch"
+    bundle_version: str = "1.0.0"
+    framework: str | None = None
+    language: str | None = None
+    certification_level: CertificationLevel
+    passed: bool
+    methodology_profiles: list[str] = Field(default_factory=list)
+    checks: list[ConformanceCheckResult] = Field(default_factory=list)
+    generated_at_ms: float = Field(default_factory=lambda: time.time() * 1000)
+    report_digest_sha256: str | None = None
+    signature_algorithm: str | None = None
+    signature: str | None = None
+
+
+def resolve_case_path(manifest_path: Path, relative_path: str) -> Path:
+    """Resolve case-local paths relative to the manifest file location."""
+    path = Path(relative_path)
+    return path if path.is_absolute() else manifest_path.resolve().parent / path

ase/conformance/schema.py

@@ -0,0 +1,37 @@
+"""Schema validation helpers for conformance manifests and results."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import jsonschema
+
+from ase.errors import ConformanceError
+
+_SCHEMAS = Path(__file__).resolve().parents[3] / "schemas"
+
+
+def validate_manifest_dict(data: dict[str, Any], source: str) -> None:
+    """Validate a conformance manifest payload against the public schema."""
+    _validate(data, _SCHEMAS / "ase_conformance_manifest.schema.json", source)
+
+
+def validate_result_dict(data: dict[str, Any], source: str) -> None:
+    """Validate a conformance result payload against the public schema."""
+    _validate(data, _SCHEMAS / "ase_conformance_result.schema.json", source)
+
+
+def _validate(data: dict[str, Any], schema_path: Path, source: str) -> None:
+    """Load one schema file and raise contextual validation errors."""
+    try:
+        schema = json.loads(schema_path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise ConformanceError(f"failed to read schema {schema_path}: {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise ConformanceError(f"invalid schema {schema_path}: {exc}") from exc
+    try:
+        jsonschema.validate(data, schema)
+    except jsonschema.ValidationError as exc:
+        raise ConformanceError(f"schema validation failed for {source}: {exc.message}") from exc

ase/conformance/service.py

@@ -0,0 +1,194 @@
+"""Load conformance manifests and execute certification checks."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+from pathlib import Path
+
+import yaml
+
+from ase.adapters.protocol import read_and_verify
+from ase.adapters.replay import trace_from_adapter_events
+from ase.conformance.model import (
+    ConformanceCheckResult,
+    ConformanceManifest,
+    ConformanceResult,
+    resolve_case_path,
+)
+from ase.conformance.schema import validate_manifest_dict, validate_result_dict
+from ase.errors import ConformanceError
+from ase.evaluation.engine import EvaluationEngine
+from ase.evaluation.trace_summary import attach_summary
+from ase.scenario.parser import parse_file
+
+
+def load_manifest(path: Path) -> ConformanceManifest:
+    """Load a YAML or JSON conformance manifest from disk."""
+    if not path.exists():
+        raise ConformanceError(f"conformance manifest not found: {path}")
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ConformanceError(f"failed to read conformance manifest {path}: {exc}") from exc
+    try:
+        data = yaml.safe_load(raw) or {}
+    except yaml.YAMLError as exc:
+        raise ConformanceError(f"invalid conformance manifest YAML in {path}: {exc}") from exc
+    validate_manifest_dict(data, str(path))
+    try:
+        return ConformanceManifest.model_validate(data)
+    except Exception as exc:
+        raise ConformanceError(f"failed to validate conformance manifest {path}: {exc}") from exc
+
+
+def certify_manifest(
+    manifest: ConformanceManifest,
+    manifest_path: Path,
+) -> ConformanceResult:
+    """Run all conformance cases and build a certification result."""
+    checks: list[ConformanceCheckResult] = []
+    eval_engine = EvaluationEngine()
+
+    for case in manifest.cases:
+        event_path = resolve_case_path(manifest_path, case.adapter_events)
+        events, verification = read_and_verify(event_path)
+        checks.append(
+            ConformanceCheckResult(
+                check_id="adapter_contract",
+                case_id=case.case_id,
+                passed=verification.passed,
+                message="adapter event stream validates"
+                if verification.passed
+                else "adapter event stream violates the contract",
+                details=verification.model_dump(),
+            )
+        )
+        trace = trace_from_adapter_events(events, case.case_id, case.name)
+
+        observed_event_types = set(verification.event_type_counts)
+        for event_type in case.required_event_types:
+            passed = event_type in observed_event_types
+            checks.append(
+                ConformanceCheckResult(
+                    check_id=f"requires_event_type:{event_type}",
+                    case_id=case.case_id,
+                    passed=passed,
+                    message=f"required event type {event_type}",
+                    details={"observed": sorted(observed_event_types)},
+                )
+            )
+
+        observed_protocols = {event.protocol for event in events if event.protocol}
+        for protocol in case.required_protocols:
+            passed = protocol in observed_protocols
+            checks.append(
+                ConformanceCheckResult(
+                    check_id=f"requires_protocol:{protocol}",
+                    case_id=case.case_id,
+                    passed=passed,
+                    message=f"required protocol {protocol}",
+                    details={"observed": sorted(observed_protocols)},
+                )
+            )
+
+        for key, minimum in case.minimum_fidelity.items():
+            observed = _observed_fidelity(trace, key)
+            checks.append(
+                ConformanceCheckResult(
+                    check_id=f"minimum_fidelity:{key}",
+                    case_id=case.case_id,
+                    passed=observed >= minimum,
+                    message=f"minimum fidelity for {key}",
+                    details={"minimum": minimum, "observed": observed},
+                )
+            )
+
+        if case.scenario:
+            scenario_path = resolve_case_path(manifest_path, case.scenario)
+            scenario = parse_file(scenario_path)
+            summary = eval_engine.evaluate(
+                trace=trace,
+                assertions=scenario.assertions,
+                context={},
+            )
+            attach_summary(trace, summary)
+            checks.append(
+                ConformanceCheckResult(
+                    check_id="scenario_assertions",
+                    case_id=case.case_id,
+                    passed=summary.passed,
+                    message="scenario assertions passed"
+                    if summary.passed
+                    else "scenario assertions failed",
+                    details={
+                        "ase_score": summary.ase_score,
+                        "failed_count": summary.failed_count,
+                    },
+                )
+            )
+
+    return ConformanceResult(
+        manifest_id=manifest.manifest_id,
+        manifest_name=manifest.name,
+        adapter_name=manifest.adapter_name,
+        adapter_version=manifest.adapter_version,
+        bundle_family=manifest.bundle_family,
+        bundle_version=manifest.bundle_version,
+        framework=manifest.framework,
+        language=manifest.language,
+        certification_level=manifest.certification_target,
+        methodology_profiles=list(manifest.methodology_profiles),
+        passed=all(check.passed for check in checks),
+        checks=checks,
+    )
+
+
+def sign_result(
+    result: ConformanceResult,
+    signing_key_env: str | None,
+) -> ConformanceResult:
+    """Attach a digest and optional HMAC signature to a certification result."""
+    payload = json.dumps(
+        result.model_dump(exclude={"report_digest_sha256", "signature_algorithm", "signature"}),
+        sort_keys=True,
+        separators=(",", ":"),
+    )
+    digest = hashlib.sha256(payload.encode("utf-8")).hexdigest()
+    updated = result.model_copy(update={"report_digest_sha256": digest})
+    if not signing_key_env:
+        validate_result_dict(updated.model_dump(), "certification result")
+        return updated
+
+    signing_key = os.environ.get(signing_key_env)
+    if not signing_key:
+        raise ConformanceError(f"missing signing key env var: {signing_key_env}")
+
+    signature = hmac.new(
+        signing_key.encode("utf-8"),
+        payload.encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+    signed = updated.model_copy(
+        update={"signature_algorithm": "hmac-sha256", "signature": signature}
+    )
+    validate_result_dict(signed.model_dump(), "signed certification result")
+    return signed
+
+
+def _observed_fidelity(trace: object, key: str) -> int:
+    """Map bundle fidelity keys onto concrete counts from a replayed trace."""
+    from ase.trace.model import Trace
+
+    assert isinstance(trace, Trace)
+    counts = {
+        "tool_calls": trace.metrics.total_tool_calls,
+        "session_events": len(trace.session_events),
+        "handoff_edges": len(trace.handoff_edges),
+        "protocol_events": len(trace.protocol_events),
+        "agent_graph_nodes": len(trace.agent_graph.nodes),
+        "external_trace_refs": len(trace.external_trace_refs),
+    }
+    return counts.get(key, 0)