ai-sdlc-framework 0.1.0__tar.gz

ai_sdlc_framework-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+*.tsbuildinfo
+.next/
+
+# Coverage
+coverage/
+.nyc_output/
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# AI-SDLC runtime artifacts
+.ai-sdlc/audit.jsonl
+
+# Package manager
+.pnpm-store/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+*.whl
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+build/
+*.pyz

ai_sdlc_framework-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: ai-sdlc-framework
+Version: 0.1.0
+Summary: Python SDK for the AI-SDLC Framework
+Project-URL: Homepage, https://github.com/ai-sdlc-framework/ai-sdlc
+Project-URL: Repository, https://github.com/ai-sdlc-framework/ai-sdlc/tree/main/sdk-python
+Project-URL: Issues, https://github.com/ai-sdlc-framework/ai-sdlc/issues
+Author: AI-SDLC Framework
+License-Expression: Apache-2.0
+Keywords: agents,ai,pipelines,quality-gates,sdlc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: opentelemetry-api>=1.20
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ai-sdlc
+
+Python SDK for the [AI-SDLC Framework](https://ai-sdlc.io) — a Kubernetes-style declarative framework for governing AI agents in software development lifecycles.
+
+## Installation
+
+```bash
+pip install ai-sdlc
+```
+
+## Quick Start
+
+```python
+from ai_sdlc.core.types import Pipeline, API_VERSION
+from ai_sdlc.core.validation import validate_resource
+from ai_sdlc.builders.builders import PipelineBuilder
+
+# Build a pipeline using the fluent API
+pipeline = (
+    PipelineBuilder("my-pipeline")
+    .add_trigger({"event": "issue.assigned"})
+    .add_provider("github", {"type": "github"})
+    .add_stage({"name": "implement"})
+    .build()
+)
+
+# Validate against JSON Schema
+result = validate_resource(pipeline.model_dump(by_alias=True))
+assert result.valid
+```
+
+## Modules
+
+| Module | Description |
+|--------|------------|
+| `core` | Pydantic models for all 5 resource types, JSON Schema validation, comparison, provenance |
+| `builders` | Fluent builder classes for resource construction |
+| `policy` | Enforcement engine, autonomy evaluation, complexity routing, authorization |
+| `adapters` | Interface Protocols, adapter registry, community stubs |
+| `reconciler` | asyncio-based reconciliation loop with domain reconcilers |
+| `agents` | Orchestration patterns, executor, multi-tier memory |
+| `security` | Sandbox, JIT credentials, kill switch, approval workflow Protocols |
+| `telemetry` | OpenTelemetry semantic conventions, structured logging |
+| `compliance` | Regulatory framework mappings (EU AI Act, NIST AI RMF, ISO 42001, etc.) |
+| `metrics` | Metric store, standard metric definitions |
+| `audit` | JSONL audit logging with tamper-evident hashing |
+
+## Requirements
+
+- Python 3.11+
+- pydantic >= 2.0
+- jsonschema >= 4.20
+- PyYAML >= 6.0
+- opentelemetry-api >= 1.20
+
+## License
+
+Apache-2.0

ai_sdlc_framework-0.1.0/README.md

@@ -0,0 +1,58 @@
+# ai-sdlc
+
+Python SDK for the [AI-SDLC Framework](https://ai-sdlc.io) — a Kubernetes-style declarative framework for governing AI agents in software development lifecycles.
+
+## Installation
+
+```bash
+pip install ai-sdlc
+```
+
+## Quick Start
+
+```python
+from ai_sdlc.core.types import Pipeline, API_VERSION
+from ai_sdlc.core.validation import validate_resource
+from ai_sdlc.builders.builders import PipelineBuilder
+
+# Build a pipeline using the fluent API
+pipeline = (
+    PipelineBuilder("my-pipeline")
+    .add_trigger({"event": "issue.assigned"})
+    .add_provider("github", {"type": "github"})
+    .add_stage({"name": "implement"})
+    .build()
+)
+
+# Validate against JSON Schema
+result = validate_resource(pipeline.model_dump(by_alias=True))
+assert result.valid
+```
+
+## Modules
+
+| Module | Description |
+|--------|------------|
+| `core` | Pydantic models for all 5 resource types, JSON Schema validation, comparison, provenance |
+| `builders` | Fluent builder classes for resource construction |
+| `policy` | Enforcement engine, autonomy evaluation, complexity routing, authorization |
+| `adapters` | Interface Protocols, adapter registry, community stubs |
+| `reconciler` | asyncio-based reconciliation loop with domain reconcilers |
+| `agents` | Orchestration patterns, executor, multi-tier memory |
+| `security` | Sandbox, JIT credentials, kill switch, approval workflow Protocols |
+| `telemetry` | OpenTelemetry semantic conventions, structured logging |
+| `compliance` | Regulatory framework mappings (EU AI Act, NIST AI RMF, ISO 42001, etc.) |
+| `metrics` | Metric store, standard metric definitions |
+| `audit` | JSONL audit logging with tamper-evident hashing |
+
+## Requirements
+
+- Python 3.11+
+- pydantic >= 2.0
+- jsonschema >= 4.20
+- PyYAML >= 6.0
+- opentelemetry-api >= 1.20
+
+## License
+
+Apache-2.0

ai_sdlc_framework-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ai-sdlc-framework"
+version = "0.1.0"
+description = "Python SDK for the AI-SDLC Framework"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [
+  { name = "AI-SDLC Framework" },
+]
+keywords = ["ai", "sdlc", "agents", "quality-gates", "pipelines"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "pydantic>=2.0,<3",
+  "jsonschema>=4.20",
+  "PyYAML>=6.0",
+  "opentelemetry-api>=1.20",
+]
+
+[project.urls]
+Homepage = "https://github.com/ai-sdlc-framework/ai-sdlc"
+Repository = "https://github.com/ai-sdlc-framework/ai-sdlc/tree/main/sdk-python"
+Issues = "https://github.com/ai-sdlc-framework/ai-sdlc/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7",
+  "pytest-asyncio>=0.21",
+  "mypy>=1.8",
+  "ruff>=0.4",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ai_sdlc"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+plugins = ["pydantic.mypy"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "TC"]
+ignore = ["SIM118"]

ai_sdlc_framework-0.1.0/src/ai_sdlc/__init__.py

@@ -0,0 +1,40 @@
+"""AI-SDLC Python SDK — native implementation of the AI-SDLC Framework."""
+
+__version__ = "0.1.0"
+
+from ai_sdlc.builders.builders import (
+    AdapterBindingBuilder,
+    AgentRoleBuilder,
+    AutonomyPolicyBuilder,
+    PipelineBuilder,
+    QualityGateBuilder,
+)
+from ai_sdlc.core.types import (
+    API_VERSION,
+    AdapterBinding,
+    AgentRole,
+    AnyResource,
+    AutonomyPolicy,
+    Pipeline,
+    QualityGate,
+    ResourceKind,
+)
+from ai_sdlc.core.validation import validate_resource
+
+__all__ = [
+    "__version__",
+    "API_VERSION",
+    "AdapterBinding",
+    "AgentRole",
+    "AnyResource",
+    "AutonomyPolicy",
+    "Pipeline",
+    "QualityGate",
+    "ResourceKind",
+    "validate_resource",
+    "AdapterBindingBuilder",
+    "AgentRoleBuilder",
+    "AutonomyPolicyBuilder",
+    "PipelineBuilder",
+    "QualityGateBuilder",
+]

ai_sdlc_framework-0.1.0/src/ai_sdlc/_utils/duration.py

@@ -0,0 +1,42 @@
+"""Parse duration strings in shorthand (60s, 5m, 2h, 1d, 2w) or ISO 8601 format."""
+
+from __future__ import annotations
+
+import re
+
+_SHORTHAND_RE = re.compile(r"^(\d+)([smhdw])$")
+_ISO_RE = re.compile(r"^PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?$")
+
+_SHORTHAND_MULTIPLIERS: dict[str, int] = {
+    "s": 1_000,
+    "m": 60_000,
+    "h": 3_600_000,
+    "d": 86_400_000,
+    "w": 604_800_000,
+}
+
+
+def parse_duration(value: str) -> int:
+    """Parse a duration string and return milliseconds.
+
+    Supports:
+      - Shorthand: ``60s``, ``5m``, ``2h``, ``1d``, ``2w``
+      - ISO 8601: ``PT1H30M``, ``PT30S``
+
+    Raises:
+        ValueError: If the duration string is invalid.
+    """
+    m = _SHORTHAND_RE.match(value)
+    if m:
+        return int(m.group(1)) * _SHORTHAND_MULTIPLIERS[m.group(2)]
+
+    m = _ISO_RE.match(value)
+    if m:
+        hours = int(m.group(1) or 0)
+        minutes = int(m.group(2) or 0)
+        seconds = int(m.group(3) or 0)
+        if hours == 0 and minutes == 0 and seconds == 0:
+            raise ValueError(f"Invalid ISO 8601 duration: {value}")
+        return (hours * 3600 + minutes * 60 + seconds) * 1000
+
+    raise ValueError(f"Invalid duration: {value}")

ai_sdlc_framework-0.1.0/src/ai_sdlc/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapter interfaces, registry, and stubs."""

ai_sdlc_framework-0.1.0/src/ai_sdlc/adapters/event_bus.py

@@ -0,0 +1,39 @@
+"""In-process EventBus implementation backed by a simple dict of handlers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+class InProcessEventBus:
+    """In-process pub/sub event bus."""
+
+    def __init__(self) -> None:
+        self._handlers: dict[str, list[Callable[..., Any]]] = {}
+
+    async def publish(self, topic: str, payload: Any) -> None:
+        for handler in self._handlers.get(topic, []):
+            handler(payload)
+
+    def subscribe(
+        self, topic: str, handler: Callable[..., Any],
+    ) -> Callable[[], None]:
+        self._handlers.setdefault(topic, []).append(handler)
+
+        def unsubscribe() -> None:
+            handlers = self._handlers.get(topic, [])
+            if handler in handlers:
+                handlers.remove(handler)
+
+        return unsubscribe
+
+    def subscriber_count(self, topic: str) -> int:
+        return len(self._handlers.get(topic, []))
+
+
+def create_in_process_event_bus() -> InProcessEventBus:
+    """Create an in-process event bus."""
+    return InProcessEventBus()

ai_sdlc_framework-0.1.0/src/ai_sdlc/adapters/git_resolver.py

@@ -0,0 +1,111 @@
+"""Git-based adapter resolver.
+
+Resolves adapter metadata from git repository references (PRD Section 9.3).
+Format: ``github.com/<org>/<repo>@<ref>``
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Protocol
+
+from ai_sdlc.adapters.registry import AdapterMetadata, validate_adapter_metadata
+from ai_sdlc.adapters.scanner import parse_metadata_yaml
+
+_GIT_REF_PATTERN = re.compile(r"^([^/]+)/([^/]+)/([^@]+)@(.+)$")
+
+
+@dataclass(frozen=True)
+class GitAdapterReference:
+    host: str
+    org: str
+    repo: str
+    ref: str
+
+
+class GitAdapterFetcher(Protocol):
+    """Abstraction for fetching raw file content from a git host."""
+
+    async def fetch(self, url: str) -> str | None: ...
+
+
+@dataclass(frozen=True)
+class GitResolveResult:
+    metadata: AdapterMetadata | None
+    error: str | None = None
+
+
+def parse_git_adapter_ref(ref: str) -> GitAdapterReference:
+    """Parse a git adapter reference string.
+
+    Expected format: ``github.com/org/repo@v1.0.0``
+    """
+    match = _GIT_REF_PATTERN.match(ref)
+    if not match:
+        raise ValueError(
+            f'Invalid git adapter reference "{ref}": '
+            "expected format <host>/<org>/<repo>@<ref>"
+        )
+    return GitAdapterReference(
+        host=match.group(1),
+        org=match.group(2),
+        repo=match.group(3),
+        ref=match.group(4),
+    )
+
+
+def build_raw_url(parsed: GitAdapterReference) -> str:
+    """Build the raw content URL for a metadata.yaml file."""
+    if parsed.host == "github.com":
+        return (
+            f"https://raw.githubusercontent.com/"
+            f"{parsed.org}/{parsed.repo}/{parsed.ref}/metadata.yaml"
+        )
+    raise ValueError(f"Unsupported git host: {parsed.host}")
+
+
+def create_stub_git_adapter_fetcher(entries: dict[str, str]) -> GitAdapterFetcher:
+    """Create a stub fetcher for testing. Maps URLs to YAML content strings."""
+
+    class _StubFetcher:
+        async def fetch(self, url: str) -> str | None:
+            return entries.get(url)
+
+    return _StubFetcher()
+
+
+async def resolve_git_adapter(
+    ref: str,
+    fetcher: GitAdapterFetcher,
+) -> GitResolveResult:
+    """Resolve adapter metadata from a git reference."""
+    try:
+        parsed = parse_git_adapter_ref(ref)
+    except ValueError as err:
+        return GitResolveResult(metadata=None, error=str(err))
+
+    try:
+        url = build_raw_url(parsed)
+    except ValueError as err:
+        return GitResolveResult(metadata=None, error=str(err))
+
+    content = await fetcher.fetch(url)
+    if content is None:
+        return GitResolveResult(
+            metadata=None, error=f"Failed to fetch metadata from {url}"
+        )
+
+    try:
+        metadata = parse_metadata_yaml(content)
+    except Exception as err:
+        return GitResolveResult(metadata=None, error=f"Invalid YAML: {err}")
+
+    validation = validate_adapter_metadata(metadata)
+    if not validation.valid:
+        return GitResolveResult(
+            metadata=None,
+            error=f"Validation failed: {'; '.join(validation.errors)}",
+        )
+
+    return GitResolveResult(metadata=metadata)

ai_sdlc_framework-0.1.0/src/ai_sdlc/adapters/github.py

@@ -0,0 +1,187 @@
+"""GitHub adapter stubs — SourceControl, IssueTracker, CIPipeline.
+
+These are stub/protocol implementations. Real API calls require
+an injected Octokit-like client (not bundled as a dependency).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+from ai_sdlc.adapters.interfaces import (
+    Branch,
+    Build,
+    BuildEvent,
+    BuildFilter,
+    BuildStatus,
+    ChangedFile,
+    CommitStatus,
+    CoverageReport,
+    CreateBranchInput,
+    CreateIssueInput,
+    CreatePRInput,
+    FileContent,
+    Issue,
+    IssueComment,
+    IssueEvent,
+    IssueFilter,
+    MergeResult,
+    MergeStrategy,
+    PREvent,
+    PRFilter,
+    PullRequest,
+    TestResults,
+    TriggerBuildInput,
+    UpdateIssueInput,
+)
+
+
+@dataclass
+class GitHubConfig:
+    org: str
+    repo: str | None = None
+    token_secret_ref: str | None = None
+
+
+class GitHubClient(Protocol):
+    """Minimal protocol for a GitHub API client."""
+
+    async def request(
+        self, method: str, url: str, **kwargs: Any,
+    ) -> Any: ...
+
+
+def _empty_async_iter() -> AsyncIterator[Any]:
+    async def _gen() -> AsyncIterator[Any]:
+        return
+        yield  # noqa: RET504  # pragma: no cover
+    return _gen()
+
+
+class _GitHubIssueTracker:
+    def __init__(self, client: GitHubClient, config: GitHubConfig) -> None:
+        self._client = client
+        self._config = config
+
+    async def list_issues(self, filter: IssueFilter) -> list[Issue]:
+        return []
+
+    async def get_issue(self, id: str) -> Issue:
+        return Issue(
+            id=id, title="", status="open",
+            url=f"https://github.com/{self._config.org}/{self._config.repo}/issues/{id}",
+        )
+
+    async def create_issue(self, input: CreateIssueInput) -> Issue:
+        return Issue(
+            id="1", title=input.title, status="open",
+            url=f"https://github.com/{self._config.org}/{self._config.repo}/issues/1",
+            description=input.description, labels=input.labels,
+            assignee=input.assignee,
+        )
+
+    async def update_issue(self, id: str, input: UpdateIssueInput) -> Issue:
+        return await self.get_issue(id)
+
+    async def transition_issue(self, id: str, transition: str) -> Issue:
+        return await self.get_issue(id)
+
+    async def add_comment(self, id: str, body: str) -> None:
+        pass
+
+    async def get_comments(self, id: str) -> list[IssueComment]:
+        return []
+
+    def watch_issues(self, filter: IssueFilter) -> AsyncIterator[IssueEvent]:
+        return _empty_async_iter()
+
+
+class _GitHubSourceControl:
+    def __init__(self, client: GitHubClient, config: GitHubConfig) -> None:
+        self._client = client
+        self._config = config
+
+    async def create_branch(self, input: CreateBranchInput) -> Branch:
+        return Branch(name=input.name, sha="stub-sha")
+
+    async def create_pr(self, input: CreatePRInput) -> PullRequest:
+        return PullRequest(
+            id="1", title=input.title,
+            source_branch=input.source_branch,
+            target_branch=input.target_branch,
+            status="open", author="stub-user",
+            url=f"https://github.com/{self._config.org}/{self._config.repo}/pull/1",
+            description=input.description,
+        )
+
+    async def merge_pr(self, id: str, strategy: MergeStrategy) -> MergeResult:
+        return MergeResult(sha="merge-sha", merged=True)
+
+    async def get_file_contents(self, path: str, ref: str) -> FileContent:
+        return FileContent(path=path, content="", encoding="utf-8")
+
+    async def list_changed_files(self, pr_id: str) -> list[ChangedFile]:
+        return []
+
+    async def set_commit_status(
+        self, sha: str, status: CommitStatus,
+    ) -> None:
+        pass
+
+    def watch_pr_events(self, filter: PRFilter) -> AsyncIterator[PREvent]:
+        return _empty_async_iter()
+
+
+class _GitHubCIPipeline:
+    def __init__(self, client: GitHubClient, config: GitHubConfig) -> None:
+        self._client = client
+        self._config = config
+
+    async def trigger_build(self, input: TriggerBuildInput) -> Build:
+        return Build(id="1", status="queued")
+
+    async def get_build_status(self, id: str) -> BuildStatus:
+        return BuildStatus(id=id, status="succeeded")
+
+    async def get_test_results(self, build_id: str) -> TestResults:
+        return TestResults(passed=0, failed=0, skipped=0)
+
+    async def get_coverage_report(self, build_id: str) -> CoverageReport:
+        return CoverageReport(line_coverage=0.0)
+
+    def watch_build_events(
+        self, filter: BuildFilter,
+    ) -> AsyncIterator[BuildEvent]:
+        return _empty_async_iter()
+
+
+def create_github_issue_tracker(
+    config: GitHubConfig, client: GitHubClient | None = None,
+) -> _GitHubIssueTracker:
+    """Create a GitHub IssueTracker adapter."""
+    return _GitHubIssueTracker(client or _NoOpClient(), config)
+
+
+def create_github_source_control(
+    config: GitHubConfig, client: GitHubClient | None = None,
+) -> _GitHubSourceControl:
+    """Create a GitHub SourceControl adapter."""
+    return _GitHubSourceControl(client or _NoOpClient(), config)
+
+
+def create_github_ci_pipeline(
+    config: GitHubConfig, client: GitHubClient | None = None,
+) -> _GitHubCIPipeline:
+    """Create a GitHub CIPipeline adapter."""
+    return _GitHubCIPipeline(client or _NoOpClient(), config)
+
+
+class _NoOpClient:
+    async def request(
+        self, method: str, url: str, **kwargs: Any,
+    ) -> Any:
+        return None