aisafe 0.1.0__py3-none-any.whl

aisafe/__init__.py

@@ -0,0 +1,141 @@
+"""
+__init__.py
+-----------
+AnyAISafe — public API surface.
+
+Runtime guardrails (use in your application):
+    from aisafe import GuardrailPipeline
+    from aisafe import PIIDetector, PromptInjectionGuard
+    from aisafe import ToxicityFilter
+    from aisafe import ToolPolicyGuard, ToolPolicy
+    from aisafe import EUAIActCompliance, RiskTier
+    from aisafe import AuditLogger
+
+Static code analyzer (use in CI / pre-commit):
+    from aisafe import EUAIActCodeAnalyzer, ScanReport
+    from aisafe import TerminalReporter, JSONReporter, SARIFReporter
+    # or via CLI: aisafe lint src/
+"""
+
+import importlib
+
+from aisafe.core.base import (
+    Action,
+    CheckResult,
+    Finding,
+    GuardrailBase,
+    GuardrailStage,
+    PipelineResult,
+    Severity,
+)
+from aisafe.core.exceptions import (
+    GuardrailBlockedError,
+    GuardrailConfigError,
+    PolicyViolationError,
+)
+from aisafe.core.pipeline import GuardrailPipeline
+
+# Input modules
+from aisafe.modules.input.pii_detector import PIIDetector, PIIRestorer
+from aisafe.modules.input.prompt_injection import PromptInjectionGuard
+from aisafe.modules.input.rate_limiter import RateLimiter
+
+# LLM judges (the base class; concrete judges need their provider SDK)
+from aisafe.modules.llm_judges.base import LLMJudgeBase
+
+# Output modules
+from aisafe.modules.output.ai_disclosure import AIDisclosureGuard
+from aisafe.modules.output.llm_output_filter import LLMOutputFilter
+from aisafe.modules.output.manipulation import ManipulationGuard
+from aisafe.modules.output.toxicity import ToxicityFilter
+
+# Policy — static code analyzer
+from aisafe.modules.policy.code_analyzer.analyzer import EUAIActCodeAnalyzer, ScanReport
+from aisafe.modules.policy.code_analyzer.reporters import (
+    JSONReporter,
+    MarkdownReporter,
+    SARIFReporter,
+    TerminalReporter,
+)
+
+# Policy — runtime guardrails
+from aisafe.modules.policy.eu_ai_act import EUAIActCompliance, RiskTier
+from aisafe.modules.policy.nist_ai_rmf import ImpactLevel, NISTAIRMFCompliance
+
+# Processing modules
+from aisafe.modules.processing.llm_tool_filter import LLMToolFilter
+from aisafe.modules.processing.tool_policy import ToolPolicy, ToolPolicyGuard
+
+# Observability is imported on first use (PEP 562). `otel.py` pulls in the
+# OpenTelemetry SDK, about a quarter of a second that every `aisafe` CLI run and every
+# agent hook would otherwise pay before doing anything; `otel.py` still guards the
+# optional dependency itself. Guards stay eager: `@register_guard` fills the registry
+# `GuardrailPipeline.from_config` reads, and a lazy guard would be an unregistered name.
+_LAZY_ATTRIBUTES = {
+    "AuditLogger": ("aisafe.modules.observability.audit_logger", "AuditLogger"),
+    "TelemetryProvider": ("aisafe.modules.observability.otel", "TelemetryProvider"),
+}
+
+
+def __getattr__(name: str):
+    target = _LAZY_ATTRIBUTES.get(name)
+    if target is None:
+        raise AttributeError(f"module 'aisafe' has no attribute {name!r}")
+    module = importlib.import_module(target[0])
+    value = getattr(module, target[1])
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))
+
+
+__version__ = "0.1.0"
+__all__ = [
+    # Pipeline
+    "GuardrailPipeline",
+    # Base types
+    "GuardrailBase",
+    "CheckResult",
+    "PipelineResult",
+    "Finding",
+    "Severity",
+    "Action",
+    "GuardrailStage",
+    # Exceptions
+    "GuardrailBlockedError",
+    "GuardrailConfigError",
+    "PolicyViolationError",
+    # Input
+    "PIIDetector",
+    "PIIRestorer",
+    "PromptInjectionGuard",
+    "RateLimiter",
+    # Processing
+    "ToolPolicyGuard",
+    "ToolPolicy",
+    "LLMToolFilter",
+    # Output
+    "ToxicityFilter",
+    "LLMOutputFilter",
+    "ManipulationGuard",
+    "AIDisclosureGuard",
+    # LLM judges
+    "LLMJudgeBase",
+    # Policy — runtime
+    "EUAIActCompliance",
+    "RiskTier",
+    "NISTAIRMFCompliance",
+    "ImpactLevel",
+    # Policy — static analyzer
+    "EUAIActCodeAnalyzer",
+    "ScanReport",
+    "TerminalReporter",
+    "JSONReporter",
+    "SARIFReporter",
+    "MarkdownReporter",
+    # Observability
+    "AuditLogger",
+    "TelemetryProvider",
+]

aisafe/cli.py

@@ -0,0 +1,197 @@
+"""
+src/aisafe/cli.py
+---------------
+Single entry point for the AnyAISafe developer tools.
+
+    aisafe --version
+    aisafe lint src/
+    aisafe lint src/ --format sarif --output results.sarif
+    aisafe misalign src/ --fail-on-warnings
+    aisafe audit . --format json -o audit-report.json
+    aisafe skill install --host all
+
+Every subcommand is a thin wrapper around a tool in `aisafe.devtools`: `lint`,
+`misalign`, `init`, `probe`, `measure`, `audit`, `skill`, `decide`, `hook`, `attest` and
+`fleet`. Each is imported
+only when invoked, so `aisafe lint` never pays for the audit engine. Everything
+after the subcommand is handed to the underlying tool untouched, so their
+flags, defaults and exit codes are unchanged:
+
+    0  no errors (warnings/info allowed)
+    1  errors found
+    2  fatal error (bad args, parse failure)
+
+`audit` adds 130 for an interrupted run; `skill` returns 1 when an install is
+refused or an installed copy differs from the packaged skill.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Callable, Sequence
+
+from aisafe import __version__
+
+__all__ = ["main", "build_parser"]
+
+_EPILOG = """
+Commands:
+  lint        EU AI Act static compliance analysis (was: euaiact-lint)
+  misalign    AI misalignment static analysis      (was: misalignment-check)
+  init        Write an ai-system-card.yaml for the system under assessment
+  probe       Send a fixed attack corpus to a live endpoint and report what got through
+  measure     Report what each guard catches, what it breaks, and what it costs
+  audit       Static AI-safety audit of a repository: findings describe evidence, never verdicts
+  skill       Install the packaged ai-safety-audit agent skill into host skill directories
+  decide      What each proposed control costs (latency, tokens, usd, human load) against the declared budgets
+  hook        Agent-host hooks: gate protected paths, secret literals and unsafe shell; re-audit edits; Stop gate
+  attest      Evaluate the level criteria against the written documents; a named owner signs the result
+  fleet       Audit every repository in a list, one subprocess each, and aggregate the counts
+
+Run `aisafe <command> --help` for a command's own options.
+
+Examples:
+  aisafe lint src/
+  aisafe lint src/ --format sarif --output results.sarif
+  aisafe lint src/ --errors-only
+  aisafe lint --staged                       # pre-commit
+  aisafe misalign src/ --fail-on-warnings
+  aisafe init --defaults
+  aisafe probe http://localhost:8000/chat --response-path '$.response'
+  aisafe measure
+  aisafe audit . --format json -o audit-report.json
+  aisafe audit . --baseline audit-baseline.json --fail-on high
+  aisafe skill install --host all
+  aisafe skill diff --host all
+  aisafe decide --requests-per-day 20000 --p99-budget-ms 250 --monthly-budget-usd 300
+  aisafe hook install --host claude --yes
+  aisafe hook list
+  aisafe attest . --owner "J. Doe <risk owner>" --html
+  aisafe attest . --check --require-level 2    # CI
+  aisafe fleet fleet.yaml --jobs 4 --proposal
+"""
+
+
+def _lint(argv: Sequence[str]) -> int:
+    from aisafe.devtools.euaiact_lint import main as lint_main
+
+    return lint_main(list(argv))
+
+
+def _misalign(argv: Sequence[str]) -> int:
+    from aisafe.devtools.misalignment_check import main as misalign_main
+
+    return misalign_main(list(argv))
+
+
+def _init(argv: Sequence[str]) -> int:
+    from aisafe.devtools.system_card import main as init_main
+
+    return init_main(list(argv))
+
+
+def _probe(argv: Sequence[str]) -> int:
+    from aisafe.devtools.probe import main as probe_main
+
+    return probe_main(list(argv))
+
+
+def _measure(argv: Sequence[str]) -> int:
+    from aisafe.devtools.measure import main as measure_main
+
+    return measure_main(list(argv))
+
+
+def _audit(argv: Sequence[str]) -> int:
+    from aisafe.devtools.audit.main import main as audit_main
+
+    return audit_main(list(argv))
+
+
+def _skill(argv: Sequence[str]) -> int:
+    from aisafe.devtools.skill import main as skill_main
+
+    return skill_main(list(argv))
+
+
+def _decide(argv: Sequence[str]) -> int:
+    from aisafe.devtools.decide import main as decide_main
+
+    return decide_main(list(argv))
+
+
+def _hook(argv: Sequence[str]) -> int:
+    from aisafe.devtools.hook import main as hook_main
+
+    return hook_main(list(argv))
+
+
+def _attest(argv: Sequence[str]) -> int:
+    from aisafe.devtools.attest import main as attest_main
+
+    return attest_main(list(argv))
+
+
+def _fleet(argv: Sequence[str]) -> int:
+    from aisafe.devtools.fleet import main as fleet_main
+
+    return fleet_main(list(argv))
+
+
+COMMANDS: dict[str, Callable[[Sequence[str]], int]] = {
+    "lint": _lint,
+    "misalign": _misalign,
+    "init": _init,
+    "probe": _probe,
+    "measure": _measure,
+    "audit": _audit,
+    "skill": _skill,
+    "decide": _decide,
+    "hook": _hook,
+    "attest": _attest,
+    "fleet": _fleet,
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="aisafe",
+        description="AnyAISafe developer tools.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_EPILOG,
+    )
+    p.add_argument(
+        "--version",
+        "-V",
+        action="version",
+        version=f"aisafe {__version__}",
+    )
+    p.add_argument(
+        "command",
+        choices=sorted(COMMANDS),
+        help="Subcommand to run",
+    )
+    # REMAINDER hands the rest through verbatim, so each tool keeps its own
+    # flags, help text and pyproject-sourced defaults.
+    p.add_argument(
+        "args",
+        nargs=argparse.REMAINDER,
+        help="Arguments passed through to the subcommand",
+    )
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    if argv is None:
+        argv = sys.argv[1:]
+    if not argv:
+        parser.print_help()
+        return 2
+    ns = parser.parse_args(argv)
+    return COMMANDS[ns.command](ns.args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

aisafe/config/__init__.py

@@ -0,0 +1,54 @@
+"""
+src/aisafe/config/__init__.py
+---------------------------
+Packaged configuration presets.
+
+The YAML presets ship as package data, so they are readable from an installed
+wheel via importlib.resources -- not just from a source checkout. A copy is
+also kept at the repo-root `config/` directory for local development; the two
+are identical.
+
+    from aisafe.config import preset_path, load_preset
+
+    GuardrailPipeline.from_config(preset_path("default.yaml"))
+    text = load_preset("eu_high_risk.yaml")
+"""
+
+from __future__ import annotations
+
+from contextlib import ExitStack
+from importlib import resources
+from pathlib import Path
+
+__all__ = ["PRESETS", "PRICES_FILE", "ATTEST_LEVELS_FILE", "preset_path", "load_preset"]
+
+# Pipeline presets: each builds a GuardrailPipeline.
+PRESETS = ("default.yaml", "eu_high_risk.yaml")
+# Other packaged data read through `preset_path()`; not pipelines, so not in PRESETS.
+PRICES_FILE = "prices.yaml"  # the dated price table `aisafe decide` joins tokens with
+ATTEST_LEVELS_FILE = "attest-levels.yaml"  # the level criteria `aisafe attest` checks
+
+# Keeps extracted resources alive for the process lifetime. Needed when the
+# package is loaded from a zip, where as_file() materialises a temp copy.
+_FILES = ExitStack()
+
+
+def preset_path(name: str) -> Path:
+    """
+    Filesystem path to a packaged preset (e.g. "default.yaml", or
+    "nemo_rails/config.yml"). Works from a wheel as well as a checkout.
+    """
+    resource = resources.files(__package__)
+    for part in name.split("/"):
+        resource = resource / part
+    if not resource.is_file():
+        raise FileNotFoundError(f"No packaged config named {name!r}")
+    return _FILES.enter_context(resources.as_file(resource))
+
+
+def load_preset(name: str) -> str:
+    """Read a packaged preset as text."""
+    resource = resources.files(__package__)
+    for part in name.split("/"):
+        resource = resource / part
+    return resource.read_text(encoding="utf-8")

aisafe/config/attest-levels.yaml

@@ -0,0 +1,58 @@
+# attest-levels.yaml
+# ---------------------------------------------------------------------------
+# The criteria `aisafe attest` evaluates. A level is reached when every criterion of
+# that level and of every level below it is met. The level is a list of criteria met
+# on a date, signed by a named owner; it is not a compliance verdict, and no renderer
+# calls it one.
+#
+# Shipped in the wheel (src/aisafe/config/) and mirrored at config/; the two are kept
+# identical by a test. `--level-criteria PATH` points `aisafe attest` at another file.
+#
+# Criterion kinds (attest.CRITERION_KINDS):
+#   report_present(max_age_days)          an audit report, fresh enough
+#   report_names_head                     report.target.git_sha equals HEAD
+#   unknown_listed                        the report carries its UNKNOWN list
+#   no_open_findings_at_or_above(severity) every finding at or above it has an accepted reason
+#   external_tools_attempted              no external scanner skipped by --no-external
+#   accepted_reasons_present              every baseline fingerprint carries a reason
+#   document_present(document, max_age_days)  a measure | probe | decision document, fresh
+#   measure_thresholds                    no guard over a declared threshold, none unavailable
+#   probe_passing_if_present              failed == 0 and errors == 0 when a probe report exists
+#   rules_closed(rules)                   no open finding of those rules
+#   card_fields_set(fields)               the system card's listed fields are not placeholders
+#   card_section_fresh(section, fields, date_field, max_age_days)  a card block set, recently dated
+#   accepted_risks_owned                  every accepted risk is written next to the owner
+#   tree_clean                            no uncommitted changes (governed = reproducible)
+# ---------------------------------------------------------------------------
+schema: aisg/1
+kind: attest-levels
+review_interval_days: 90
+levels:
+  - level: 0
+    name: audited
+    criteria:
+      - {id: L0.report, kind: report_present, max_age_days: 30}
+      - {id: L0.commit, kind: report_names_head}
+      - {id: L0.unknown, kind: unknown_listed}
+  - level: 1
+    name: triaged
+    criteria:
+      - {id: L1.no_open_high, kind: no_open_findings_at_or_above, severity: high}
+      - {id: L1.scanners, kind: external_tools_attempted}
+      - {id: L1.reasons, kind: accepted_reasons_present}
+  - level: 2
+    name: measured
+    criteria:
+      - {id: L2.measure, kind: document_present, document: measure, max_age_days: 30}
+      - {id: L2.thresholds, kind: measure_thresholds}
+      - {id: L2.probe, kind: probe_passing_if_present}
+      - {id: L2.decision, kind: document_present, document: decision, max_age_days: 30}
+      - {id: L2.evals_ci, kind: rules_closed, rules: [AUD-901, AUD-903]}
+  - level: 3
+    name: governed
+    criteria:
+      - {id: L3.card, kind: card_fields_set, fields: [system.purpose, affected_persons, incident_contact, risk_tier, deployment]}
+      - {id: L3.prompt_audit, kind: card_section_fresh, section: prompt_audit, fields: [reviewed_at, reviewer], date_field: reviewed_at, max_age_days: 180}
+      - {id: L3.controls, kind: rules_closed, rules: [AUD-107, AUD-701, AUD-702, AUD-703, AUD-1107]}
+      - {id: L3.owner, kind: accepted_risks_owned}
+      - {id: L3.tree, kind: tree_clean}

aisafe/config/default.yaml

@@ -0,0 +1,163 @@
+# config/default.yaml
+# -------------------------------------------------------
+# AnyAISafe — Default Pipeline Configuration
+# -------------------------------------------------------
+# All modules are optional. Set enabled: false to skip any.
+# Override per environment: production.yaml, eu_high_risk.yaml, etc.
+
+pipeline:
+  mode: async
+  parallel_checks: true        # Run input checks in parallel for lower latency
+  fail_open: false             # If true, guardrail errors allow traffic through (NOT recommended for prod)
+  request_timeout: 30.0        # Max seconds for the LLM call in run_full() (0 = no timeout)
+
+# ⑤ OBSERVABILITY (OpenTelemetry)
+# Install:  pip install "aisafe[otel]"
+# Pass a TelemetryProvider instance to GuardrailPipeline(telemetry_provider=...).
+# Backends: set exporter to "otlp" and point otlp_endpoint at any OTLP collector
+# (Jaeger, Zipkin, Datadog, Honeycomb, Grafana Tempo, AWS X-Ray via ADOT, etc.)
+#
+# observability:
+#   enabled: true
+#   service_name: my-ai-system
+#   exporter: console              # "console" | "otlp" | "none"
+#   otlp_endpoint: http://localhost:4317
+#   otlp_protocol: grpc            # "grpc" | "http"
+#   metric_export_interval_ms: 60000
+
+# ① INPUT GUARDRAILS
+input:
+  pii_detector:
+    enabled: true
+    action: redact             # redact | block | flag
+    entities:
+      - EMAIL
+      - PHONE_US
+      - PHONE_INTL
+      - SSN
+      - CREDIT_CARD
+      - IP_ADDRESS
+    use_presidio: false        # Set true if presidio-analyzer is installed
+
+  prompt_injection:
+    enabled: true
+    sensitivity: medium        # low | medium | high
+    check_base64: true
+    llm_judge: false           # Enable for high-security deployments (+latency)
+    log_attempts: true
+
+  topic_classifier:
+    enabled: false             # Enable and configure allowed_topics for your use case
+    # allowed_topics:
+    #   - customer_support
+    #   - billing
+    #   - product_info
+    # fallback_message: "I can only help with customer support, billing, and product topics."
+
+  toxicity_input:
+    enabled: false
+    # threshold: 0.8
+    # categories: [self_harm_promotion, violent_threats, dangerous_instructions]
+
+  rate_limiter:
+    enabled: true
+    requests_per_minute: 60
+    tokens_per_day: 100000
+    key_field: user_id         # context field to key limits on
+    count_tokens: true
+
+# ② PROCESSING GUARDRAILS (tool use / agent control)
+processing:
+  tool_policy:
+    enabled: true
+    default_deny: true
+    default_role: user
+    approval_timeout: 30.0         # Seconds to wait for approval callback before denying
+    max_tool_calls_per_session: 0  # 0 = unlimited; set e.g. 50 to cap agentic loops
+    max_calls_per_tool: 0          # 0 = unlimited per-tool cap
+    # require_approval:
+    #   - send_email
+    #   - database_write
+    #   - payment_*
+    # policies:
+    #   user:
+    #     allow: [search, calculator, fetch_url, read_file]
+    #     deny: [file_write, exec_code, shell_command]
+    #     argument_rules:           # Argument-level constraints per tool
+    #       read_file:
+    #         path: "./data/*"      # Only allow reads inside ./data/
+    #       fetch_url:
+    #         url: "https://*.trusted-domain.com/*"
+    #   admin:
+    #     allow: ["*"]
+    #     deny: [shell_command]
+
+  context_control:
+    enabled: false             # Not yet implemented
+    # max_rag_results: 5
+    # allowed_collections: [public_docs, kb_articles]
+
+  memory_hygiene:
+    enabled: false             # Not yet implemented
+    # ttl_seconds: 3600
+    # max_memory_tokens: 4096
+
+# ③ OUTPUT GUARDRAILS
+output:
+  toxicity_output:
+    enabled: true
+    threshold: 0.7
+    action: block              # block | warn | flag
+    categories:
+      - self_harm_promotion
+      - violent_threats
+      - dangerous_instructions
+    use_llm_judge: false       # Enable for higher accuracy (+latency)
+
+  manipulation_output:
+    enabled: true
+    action: flag               # flag | block; manipulation is contextual, measure before blocking
+    min_severity: medium       # findings below it are recorded, never acted on
+    use_llm_judge: false       # ClaudeJudge(mode="manipulation"), one model call per response
+
+  ai_disclosure_output:
+    enabled: true
+    action: flag               # flag | redact | block
+    append_when: on_claim      # never | on_claim | always
+
+  pii_restorer:
+    enabled: false             # Enable when using PIIDetector(action="tokenize") on input
+    # Restores <PII:TYPE:N> tokens to original values after LLM response
+
+  hallucination:
+    enabled: false             # Not yet implemented
+    # threshold: 0.6
+    # citation_required: false
+
+  schema_validator:
+    enabled: false             # Not yet implemented
+    # schema: {}
+    # strict: false
+
+  content_policy:
+    enabled: false             # Not yet implemented
+    # rules: []
+
+# ④ POLICY COMPLIANCE
+policy:
+  eu_ai_act:
+    enabled: true
+    risk_tier: limited         # unacceptable | high | limited | minimal
+    system_id: my-ai-system
+    provider_name: My Organization
+    enable_audit_log: false    # Set true for high-risk tier
+    audit_log_path: audit/eu_ai_act.jsonl
+    audit_retention_days: 365
+    check_prohibited: true
+    check_high_risk_indicators: true
+    strict_mode: true
+
+  gdpr:
+    enabled: false
+    # data_minimization: true
+    # purpose_limitation: true