aisoc-sdk 4.0.0__tar.gz

aisoc_sdk-4.0.0/.gitignore

@@ -0,0 +1,162 @@
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Build outputs
+dist/
+build/
+.next/
+out/
+.turbo/
+# T3.8 — generated Storybook static bundle. The source lives in
+# apps/web/.storybook + apps/web/stories; the built bundle is uploaded
+# as a CI artifact rather than committed.
+apps/web/storybook-static/
+*.egg-info/
+__pycache__/
+*.pyc
+*.pyo
+
+# Go
+*.exe
+*.test
+vendor/
+bin/
+
+# Terraform
+.terraform/
+*.tfstate
+*.tfstate.backup
+.terraform.lock.hcl
+*.tfvars
+!terraform.tfvars.example
+
+# Python
+.venv/
+venv/
+.eval-test-venv/
+.mypy_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+# Phase 2.2 — vitest v8 coverage outputs (apps/web/coverage/) and
+# any other per-service coverage dump. Generated on every CI run,
+# uploaded as artefacts — never committed.
+coverage/
+**/coverage/
+# BUT keep app-source directories literally named `coverage` (the
+# /tools/coverage route, and `components/coverage/` behind /coverage-advisor).
+# The rules above are for generated test-coverage output; without these
+# negations the coverage tool page silently drops from the build.
+#
+# `components/` was missing here, which is worse than it sounds: the component
+# was tracked because it predates the rule, so nothing looked wrong, but every
+# *new* file beside it — a test especially — was ignored on `git add -A` and
+# never reached CI. A test that cannot be committed is indistinguishable from
+# a test that passes.
+!apps/web/src/app/**/coverage/
+!apps/web/src/app/**/coverage/**
+!apps/web/src/components/coverage/
+!apps/web/src/components/coverage/**
+*.lcov
+
+# IDE
+.idea/
+.vscode/
+.cursor/
+.claude/
+*.swp
+*.swo
+
+# Go test/build binaries inside plugins
+plugins/**/*-build-test
+plugins/**/*-build
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+logs/
+*.log
+# But: the AIT-LDS fidelity-benchmark fixture ships an Apache CLF
+# access.log on purpose (T5.3 in v8.0). It is committed test data,
+# not a runtime log, so unblock it explicitly.
+!services/agents/tests/eval_data/**/*.log
+
+# Docker
+.docker/
+
+# Secrets
+*.pem
+*.key
+*.crt
+secrets/
+.gstack/
+
+# Local eval / build artifacts
+eval_report.json
+eval_mitre_accuracy_report.json
+.gocache/
+*.tsbuildinfo
+
+# PR body scratch files (local working copy, never committed)
+.pr-body-*.md
+
+# Local progress tracking (per AGENTS.md preference, not committed)
+PROGRESS.md
+PR_TRIAGE.md
+
+# Acceptance harness ledger (.aisoc/acceptance-history.jsonl is per-machine and
+# accumulates across runs — useful for "is this getting slower?" but not for
+# version control. Same applies to any other harness state we drop in here.)
+.aisoc/
+
+# Detection-import upstream clones (populated by tools.detection_import)
+.import-cache/
+
+# Docusaurus generated cache (apps/docs)
+apps/docs/.docusaurus/
+apps/docs/build/
+
+# Local QA artifacts (screenshots from manual UI checks)
+apps/web/.qa-screenshots/
+
+# Runtime playbook store. `PlaybookStore` keeps the bundled corpus read-only and
+# writes every mutation to `index.json` in the same directory, so anything that
+# exercises `POST /api/v1/playbooks` — a test, a local run, a reproduction of a
+# bug — leaves a several-thousand-line file behind. Committing it ships whatever
+# the last run happened to hold as if it were curated content, and the playbook
+# schema lint counts it as a 65th file.
+services/agents/data/playbooks/index.json
+
+# Marketplace index staged into the API service build context at deploy time
+# (see infra/fly/fly-demo-deploy.sh). The canonical source is marketplace/index.json
+# at the repo root; the API Dockerfile only sees its own dir as build context, so
+# the deploy script copies the index in just-in-time. We never commit the copy.
+services/api/marketplace/
+
+# Live-dumped graph schema produced by `scripts/export_graph_schema.py`
+# (default mode). The source of truth is `schemas/graph-schema.yaml`; the
+# `-current.yaml` file is a runtime artefact that varies by environment.
+schemas/graph-schema-current.yaml
+
+
+# Compiled Go binaries. `services/demo-producer/demo-producer` was committed as
+# a 6.9 MB macOS arm64 executable in a repository whose Dockerfile builds a
+# GOOS=linux one — nothing consumed it, nothing rebuilt it, and running the
+# documented `go build ./...` silently overwrote it and dirtied the tree.
+/services/demo-producer/demo-producer
+/services/enrichment/enrichment
+/services/ingest/ingest
+
+# Generated by scripts/resolve_port_conflicts.py when a host port AiSOC
+# publishes is already in use. Machine-specific by definition.
+docker-compose.ports.yml

aisoc_sdk-4.0.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: aisoc-sdk
+Version: 4.0.0
+Summary: Python client SDK for AiSOC — typed httpx client
+Project-URL: Homepage, https://github.com/beenuar/AiSOC
+Project-URL: Documentation, https://beenuar.github.io/AiSOC
+Project-URL: Repository, https://github.com/beenuar/AiSOC
+Project-URL: Issues, https://github.com/beenuar/AiSOC/issues
+Author-email: AiSOC Contributors <oss@aisoc.io>
+License: MIT
+Keywords: aisoc,client,sdk,security,soc
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy<3,>=2.3.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.16.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# aisoc-sdk
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+[![PyPI release](https://img.shields.io/badge/pypi-not%20yet%20published-f59e0b)](https://github.com/beenuar/AiSOC/blob/main/CHANGELOG.md)
+
+Async Python client SDK for [AiSOC](https://github.com/beenuar/AiSOC).
+
+> **Status — monorepo today, not yet on PyPI.** `pip install aisoc-sdk` does not resolve; install from the monorepo source path below. The import path (`aisoc_sdk`) and API surface stay identical once it ships.
+
+## Installation
+
+```bash
+# Today (from this monorepo):
+git clone https://github.com/beenuar/AiSOC.git
+cd AiSOC && pip install -e packages/sdk-py
+
+# Not yet on PyPI — the upload is blocked on registry credentials,
+# which is an account action rather than a code change. Until then, install
+# from source with the command above.
+#   pip install aisoc-sdk
+```
+
+## Quick start
+
+```python
+import asyncio
+from aisoc_sdk import AiSOCClient
+
+
+async def main():
+    async with AiSOCClient(
+        base_url="https://your-aisoc.example.com",
+        token="aisoc_...",
+    ) as client:
+        # List critical open alerts
+        alerts = await client.alerts.list(severity="critical", status="open")
+        print(f"Found {alerts.total} critical alerts")
+
+        # Create a case
+        case = await client.cases.create(
+            title="Suspicious lateral movement",
+            priority="high",
+        )
+
+        # Trigger a playbook
+        run = await client.playbooks.run(
+            "isolate-host",
+            trigger_data={"host_id": "srv-prod-42", "case_id": case.id},
+        )
+        print("Playbook run:", run.run_id)
+
+
+asyncio.run(main())
+```
+
+## GraphQL
+
+```python
+async with AiSOCClient(base_url="...", token="...") as client:
+    result = await client.graphql("""
+        query {
+            alerts(pageSize: 10, status: "open") {
+                items { id title severity }
+            }
+        }
+    """)
+```
+
+## API reference
+
+All resource methods are `async` and return typed Pydantic models.
+
+| Attribute | Methods |
+|---|---|
+| `client.alerts` | `list(filters?)`, `get(id)`, `update(id, **data)` |
+| `client.cases` | `list(filters?)`, `get(id)`, `create(**data)`, `update(id, **data)`, `delete(id)` |
+| `client.detections` | `list(page, page_size)`, `get(id)` |
+| `client.connectors` | `list(page, page_size)`, `get(id)` |
+| `client.playbooks` | `list(page, page_size)`, `get(id)`, `create(**data)`, `update(id, **data)`, `delete(id)`, `run(id, trigger_data?)`, `get_run(run_id)` |
+| `client.api_keys` | `list()`, `create(req)`, `revoke(id)` |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

aisoc_sdk-4.0.0/README.md

@@ -0,0 +1,87 @@
+# aisoc-sdk
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+[![PyPI release](https://img.shields.io/badge/pypi-not%20yet%20published-f59e0b)](https://github.com/beenuar/AiSOC/blob/main/CHANGELOG.md)
+
+Async Python client SDK for [AiSOC](https://github.com/beenuar/AiSOC).
+
+> **Status — monorepo today, not yet on PyPI.** `pip install aisoc-sdk` does not resolve; install from the monorepo source path below. The import path (`aisoc_sdk`) and API surface stay identical once it ships.
+
+## Installation
+
+```bash
+# Today (from this monorepo):
+git clone https://github.com/beenuar/AiSOC.git
+cd AiSOC && pip install -e packages/sdk-py
+
+# Not yet on PyPI — the upload is blocked on registry credentials,
+# which is an account action rather than a code change. Until then, install
+# from source with the command above.
+#   pip install aisoc-sdk
+```
+
+## Quick start
+
+```python
+import asyncio
+from aisoc_sdk import AiSOCClient
+
+
+async def main():
+    async with AiSOCClient(
+        base_url="https://your-aisoc.example.com",
+        token="aisoc_...",
+    ) as client:
+        # List critical open alerts
+        alerts = await client.alerts.list(severity="critical", status="open")
+        print(f"Found {alerts.total} critical alerts")
+
+        # Create a case
+        case = await client.cases.create(
+            title="Suspicious lateral movement",
+            priority="high",
+        )
+
+        # Trigger a playbook
+        run = await client.playbooks.run(
+            "isolate-host",
+            trigger_data={"host_id": "srv-prod-42", "case_id": case.id},
+        )
+        print("Playbook run:", run.run_id)
+
+
+asyncio.run(main())
+```
+
+## GraphQL
+
+```python
+async with AiSOCClient(base_url="...", token="...") as client:
+    result = await client.graphql("""
+        query {
+            alerts(pageSize: 10, status: "open") {
+                items { id title severity }
+            }
+        }
+    """)
+```
+
+## API reference
+
+All resource methods are `async` and return typed Pydantic models.
+
+| Attribute | Methods |
+|---|---|
+| `client.alerts` | `list(filters?)`, `get(id)`, `update(id, **data)` |
+| `client.cases` | `list(filters?)`, `get(id)`, `create(**data)`, `update(id, **data)`, `delete(id)` |
+| `client.detections` | `list(page, page_size)`, `get(id)` |
+| `client.connectors` | `list(page, page_size)`, `get(id)` |
+| `client.playbooks` | `list(page, page_size)`, `get(id)`, `create(**data)`, `update(id, **data)`, `delete(id)`, `run(id, trigger_data?)`, `get_run(run_id)` |
+| `client.api_keys` | `list()`, `create(req)`, `revoke(id)` |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

aisoc_sdk-4.0.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aisoc-sdk"
+version = "4.0.0"
+description = "Python client SDK for AiSOC — typed httpx client"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["aisoc", "soc", "security", "client", "sdk"]
+authors = [{ name = "AiSOC Contributors", email = "oss@aisoc.io" }]
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-httpx>=0.30",
+    "mypy>=2.3.1,<3",
+    "ruff>=0.16.8,<0.17",
+]
+
+[project.urls]
+Homepage = "https://github.com/beenuar/AiSOC"
+Documentation = "https://beenuar.github.io/AiSOC"
+Repository = "https://github.com/beenuar/AiSOC"
+Issues = "https://github.com/beenuar/AiSOC/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aisoc_sdk"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.mypy]
+strict = true
+# Pinned, like the other five trees that declare [tool.mypy]. Without it
+# mypy resolves the standard library for whatever interpreter it happens to
+# run on, so this tree's share of the recorded baseline moved whenever CI's
+# Python did — and the ratchet would red on a workflow change that touched
+# none of this code. 3.11 is the interpreter every service image ships and
+# the one CI now runs.
+python_version = "3.11"

aisoc_sdk-4.0.0/src/aisoc_sdk/__init__.py

@@ -0,0 +1,52 @@
+"""aisoc-sdk — Python client for AiSOC.
+
+Usage::
+
+    from aisoc_sdk import AiSOCClient
+
+    async with AiSOCClient(base_url="https://soc.example.com", token="aisoc_...") as client:
+        alerts = await client.alerts.list(severity="critical")
+"""
+
+from .client import AiSOCClient, AiSOCError
+from .models import (
+    Alert,
+    AlertFilters,
+    AlertSeverity,
+    AlertStatus,
+    ApiKey,
+    ApiKeyCreateRequest,
+    ApiKeyCreateResponse,
+    Case,
+    CaseFilters,
+    CasePriority,
+    CaseStatus,
+    Connector,
+    DetectionRule,
+    Page,
+    Playbook,
+    PlaybookRun,
+)
+
+__all__ = [
+    "AiSOCClient",
+    "AiSOCError",
+    "Alert",
+    "AlertFilters",
+    "AlertSeverity",
+    "AlertStatus",
+    "ApiKey",
+    "ApiKeyCreateRequest",
+    "ApiKeyCreateResponse",
+    "Case",
+    "CaseFilters",
+    "CasePriority",
+    "CaseStatus",
+    "Connector",
+    "DetectionRule",
+    "Page",
+    "Playbook",
+    "PlaybookRun",
+]
+
+__version__ = "4.0.0"

aisoc_sdk-4.0.0/src/aisoc_sdk/client.py

@@ -0,0 +1,292 @@
+"""AiSOCClient — async httpx-based client for the AiSOC REST API.
+
+Usage::
+
+    async with AiSOCClient(base_url="https://soc.example.com", token="aisoc_...") as c:
+        page = await c.alerts.list(severity="critical")
+        case = await c.cases.create(title="Incident", priority="high")
+        run  = await c.playbooks.run("isolate-host", trigger_data={"host": "srv-42"})
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Type, TypeVar
+
+import httpx
+from pydantic import TypeAdapter
+
+from .models import (
+    Alert,
+    AlertFilters,
+    ApiKey,
+    ApiKeyCreateRequest,
+    ApiKeyCreateResponse,
+    Case,
+    CaseFilters,
+    Connector,
+    DetectionRule,
+    Page,
+    Playbook,
+    PlaybookRun,
+)
+
+T = TypeVar("T")
+
+
+# ─── Error ────────────────────────────────────────────────────────────────────
+
+
+class AiSOCError(Exception):
+    """Raised when the AiSOC API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"AiSOC API {status_code}: {detail}")
+
+
+# ─── Base resource client ─────────────────────────────────────────────────────
+
+
+class _ResourceClient:
+    def __init__(self, http: httpx.AsyncClient) -> None:
+        self._http = http
+
+    async def _get(
+        self,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+        model: Optional[Type[T]] = None,
+    ) -> Any:
+        r = await self._http.get(path, params=self._clean(params))
+        self._raise(r)
+        if model is not None:
+            return TypeAdapter(model).validate_python(r.json())
+        return r.json()
+
+    async def _post(self, path: str, body: Any, model: Optional[Type[T]] = None) -> Any:
+        r = await self._http.post(path, json=body)
+        self._raise(r)
+        if model is not None:
+            return TypeAdapter(model).validate_python(r.json())
+        return r.json()
+
+    async def _patch(self, path: str, body: Any, model: Optional[Type[T]] = None) -> Any:
+        r = await self._http.patch(path, json=body)
+        self._raise(r)
+        if model is not None:
+            return TypeAdapter(model).validate_python(r.json())
+        return r.json()
+
+    async def _put(self, path: str, body: Any, model: Optional[Type[T]] = None) -> Any:
+        r = await self._http.put(path, json=body)
+        self._raise(r)
+        if model is not None:
+            return TypeAdapter(model).validate_python(r.json())
+        return r.json()
+
+    async def _delete(self, path: str) -> None:
+        r = await self._http.delete(path)
+        self._raise(r)
+
+    @staticmethod
+    def _clean(params: Optional[dict[str, Any]]) -> dict[str, Any]:
+        if params is None:
+            return {}
+        return {k: v for k, v in params.items() if v is not None}
+
+    @staticmethod
+    def _raise(r: httpx.Response) -> None:
+        if not r.is_success:
+            try:
+                detail = r.json().get("detail", r.text)
+            except Exception:
+                detail = r.text
+            raise AiSOCError(r.status_code, detail)
+
+
+# ─── Resource sub-clients ─────────────────────────────────────────────────────
+
+
+class AlertsClient(_ResourceClient):
+    async def list(self, filters: Optional[AlertFilters] = None, **kwargs: Any) -> Page[Alert]:
+        params = filters.model_dump(exclude_none=True) if filters else self._clean(kwargs)
+        return await self._get("/api/v1/alerts", params, Page[Alert])
+
+    async def get(self, alert_id: str) -> Alert:
+        return await self._get(f"/api/v1/alerts/{alert_id}", model=Alert)
+
+    async def update(self, alert_id: str, **data: Any) -> Alert:
+        return await self._patch(f"/api/v1/alerts/{alert_id}", data, Alert)
+
+
+class CasesClient(_ResourceClient):
+    async def list(self, filters: Optional[CaseFilters] = None, **kwargs: Any) -> Page[Case]:
+        params = filters.model_dump(exclude_none=True) if filters else self._clean(kwargs)
+        return await self._get("/api/v1/cases", params, Page[Case])
+
+    async def get(self, case_id: str) -> Case:
+        return await self._get(f"/api/v1/cases/{case_id}", model=Case)
+
+    async def create(self, **data: Any) -> Case:
+        return await self._post("/api/v1/cases", data, Case)
+
+    async def update(self, case_id: str, **data: Any) -> Case:
+        return await self._patch(f"/api/v1/cases/{case_id}", data, Case)
+
+    # There is no `delete`. The API serves no DELETE on a case — a case is
+    # closed by patching its status, and the method that used to be here
+    # called a route `services/api` has never declared.
+
+
+class DetectionsClient(_ResourceClient):
+    # The route is `/detection/rules`, singular, and this client asked for
+    # `/detections` — so every method here answered 404 against a real
+    # deployment while its mocked test passed.
+    async def list(self, page: int = 1, page_size: int = 20) -> Page[DetectionRule]:
+        return await self._get(
+            "/api/v1/detection/rules", {"page": page, "page_size": page_size}, Page[DetectionRule]
+        )
+
+    async def get(self, rule_id: str) -> DetectionRule:
+        return await self._get(f"/api/v1/detection/rules/{rule_id}", model=DetectionRule)
+
+
+class ConnectorsClient(_ResourceClient):
+    async def list(self, page: int = 1, page_size: int = 20) -> Page[Connector]:
+        return await self._get(
+            "/api/v1/connectors", {"page": page, "page_size": page_size}, Page[Connector]
+        )
+
+    async def get(self, connector_id: str) -> Connector:
+        return await self._get(f"/api/v1/connectors/{connector_id}", model=Connector)
+
+
+class PlaybooksClient(_ResourceClient):
+    async def list(self, page: int = 1, page_size: int = 20) -> Page[Playbook]:
+        return await self._get(
+            "/api/v1/playbooks", {"page": page, "page_size": page_size}, Page[Playbook]
+        )
+
+    async def get(self, playbook_id: str) -> Playbook:
+        return await self._get(f"/api/v1/playbooks/{playbook_id}", model=Playbook)
+
+    async def create(self, **data: Any) -> Playbook:
+        return await self._post("/api/v1/playbooks", data, Playbook)
+
+    # PUT, not PATCH: `playbooks.py` declares `@router.put("/{playbook_id}")`
+    # and no patch route, so the previous verb returned 405.
+    async def update(self, playbook_id: str, **data: Any) -> Playbook:
+        return await self._put(f"/api/v1/playbooks/{playbook_id}", data, Playbook)
+
+    async def delete(self, playbook_id: str) -> None:
+        return await self._delete(f"/api/v1/playbooks/{playbook_id}")
+
+    async def run(
+        self,
+        playbook_id: str,
+        trigger_data: Optional[dict[str, Any]] = None,
+    ) -> PlaybookRun:
+        return await self._post(
+            f"/api/v1/playbooks/{playbook_id}/run",
+            {"trigger_data": trigger_data or {}},
+            PlaybookRun,
+        )
+
+    async def get_run(self, run_id: str) -> PlaybookRun:
+        return await self._get(f"/api/v1/playbooks/runs/{run_id}", model=PlaybookRun)
+
+
+class ApiKeysClient(_ResourceClient):
+    async def list(self) -> Page[ApiKey]:
+        return await self._get("/api/v1/api-keys", model=Page[ApiKey])
+
+    async def create(self, req: ApiKeyCreateRequest) -> ApiKeyCreateResponse:
+        return await self._post(
+            "/api/v1/api-keys",
+            req.model_dump(exclude_none=True),
+            ApiKeyCreateResponse,
+        )
+
+    async def revoke(self, key_id: str) -> None:
+        return await self._delete(f"/api/v1/api-keys/{key_id}")
+
+
+# ─── Main client ─────────────────────────────────────────────────────────────
+
+
+class AiSOCClient:
+    """Async Python client for the AiSOC REST API.
+
+    Must be used as an async context manager::
+
+        async with AiSOCClient(base_url="...", token="...") as client:
+            alerts = await client.alerts.list()
+
+    Or manage the lifecycle manually::
+
+        client = AiSOCClient(base_url="...", token="...")
+        await client.__aenter__()
+        try:
+            ...
+        finally:
+            await client.__aexit__(None, None, None)
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        timeout: float = 30.0,
+        headers: Optional[dict[str, str]] = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._timeout = timeout
+        self._extra_headers = headers or {}
+        self._http: Optional[httpx.AsyncClient] = None
+
+        # Placeholders — initialised in __aenter__
+        self.alerts: AlertsClient
+        self.cases: CasesClient
+        self.detections: DetectionsClient
+        self.connectors: ConnectorsClient
+        self.playbooks: PlaybooksClient
+        self.api_keys: ApiKeysClient
+
+    async def __aenter__(self) -> "AiSOCClient":
+        self._http = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={
+                "Authorization": f"Bearer {self._token}",
+                "Content-Type": "application/json",
+                **self._extra_headers,
+            },
+            timeout=self._timeout,
+        )
+        self.alerts = AlertsClient(self._http)
+        self.cases = CasesClient(self._http)
+        self.detections = DetectionsClient(self._http)
+        self.connectors = ConnectorsClient(self._http)
+        self.playbooks = PlaybooksClient(self._http)
+        self.api_keys = ApiKeysClient(self._http)
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        if self._http is not None:
+            await self._http.aclose()
+            self._http = None
+
+    async def graphql(
+        self,
+        query: str,
+        variables: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Execute a GraphQL query against the /graphql endpoint."""
+        if self._http is None:
+            raise RuntimeError("Use AiSOCClient as an async context manager")
+        r = await self._http.post("/graphql", json={"query": query, "variables": variables})
+        if not r.is_success:
+            raise AiSOCError(r.status_code, r.text)
+        return r.json()  # type: ignore[return-value]

aisoc_sdk-4.0.0/src/aisoc_sdk/models.py

@@ -0,0 +1,208 @@
+"""Pydantic models mirroring the AiSOC OpenAPI schema."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, Generic, List, Optional, TypeVar
+
+from pydantic import BaseModel, ConfigDict
+
+
+# ── Enums ─────────────────────────────────────────────────────────────────────
+
+
+class AlertSeverity(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+
+
+class AlertStatus(str, Enum):
+    OPEN = "open"
+    IN_PROGRESS = "in_progress"
+    CLOSED = "closed"
+    FALSE_POSITIVE = "false_positive"
+
+
+class CasePriority(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+class CaseStatus(str, Enum):
+    OPEN = "open"
+    INVESTIGATING = "investigating"
+    RESOLVED = "resolved"
+    CLOSED = "closed"
+
+
+# ── Core models ───────────────────────────────────────────────────────────────
+
+_M = ConfigDict(populate_by_name=True, from_attributes=True)
+
+
+class Alert(BaseModel):
+    model_config = _M
+
+    id: str
+    tenant_id: str
+    title: str
+    severity: AlertSeverity
+    status: AlertStatus
+    source: str
+    source_ref: Optional[str] = None
+    mitre_tactics: List[str] = []
+    ai_score: Optional[float] = None
+    case_id: Optional[str] = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class Case(BaseModel):
+    model_config = _M
+
+    id: str
+    tenant_id: str
+    case_number: str
+    title: str
+    status: CaseStatus
+    priority: CasePriority
+    assignee: Optional[str] = None
+    mitre_tactics: List[str] = []
+    alert_ids: List[str] = []
+    created_at: datetime
+    updated_at: datetime
+
+
+class DetectionRule(BaseModel):
+    model_config = _M
+
+    id: str
+    tenant_id: str
+    name: str
+    description: Optional[str] = None
+    rule_language: str
+    severity: AlertSeverity
+    enabled: bool
+    created_at: datetime
+    updated_at: datetime
+
+
+class Connector(BaseModel):
+    model_config = _M
+
+    id: str
+    tenant_id: str
+    name: str
+    connector_type: str
+    is_enabled: bool
+    health_status: str
+    events_ingested: int = 0
+    created_at: datetime
+    updated_at: datetime
+
+
+class PlaybookStep(BaseModel):
+    model_config = _M
+
+    id: str
+    name: str
+    type: str
+    action: Optional[str] = None
+    parameters: Optional[dict[str, Any]] = None
+    next_steps: List[str] = []
+
+
+class Playbook(BaseModel):
+    model_config = _M
+
+    id: str
+    name: str
+    description: Optional[str] = None
+    version: str
+    steps: List[PlaybookStep] = []
+    trigger_conditions: Optional[dict[str, Any]] = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class PlaybookRun(BaseModel):
+    model_config = _M
+
+    run_id: str
+    playbook_id: str
+    status: str
+    started_at: datetime
+    completed_at: Optional[datetime] = None
+    trigger_data: Optional[dict[str, Any]] = None
+    step_results: Optional[dict[str, Any]] = None
+
+
+class ApiKey(BaseModel):
+    model_config = _M
+
+    id: str
+    name: str
+    prefix: str
+    scopes: List[str]
+    expires_at: Optional[datetime] = None
+    last_used_at: Optional[datetime] = None
+    created_at: datetime
+
+
+# ── Pagination ────────────────────────────────────────────────────────────────
+
+T = TypeVar("T")
+
+
+class Page(BaseModel, Generic[T]):
+    model_config = _M
+
+    items: List[T]
+    total: int
+    page: int
+    page_size: int
+
+
+# ── Request / response helpers ────────────────────────────────────────────────
+
+
+class AlertFilters(BaseModel):
+    model_config = _M
+
+    severity: Optional[AlertSeverity] = None
+    status: Optional[AlertStatus] = None
+    case_id: Optional[str] = None
+    search: Optional[str] = None
+    page: int = 1
+    page_size: int = 20
+
+
+class CaseFilters(BaseModel):
+    model_config = _M
+
+    status: Optional[CaseStatus] = None
+    priority: Optional[CasePriority] = None
+    assignee: Optional[str] = None
+    page: int = 1
+    page_size: int = 20
+
+
+class ApiKeyCreateRequest(BaseModel):
+    model_config = _M
+
+    name: str
+    scopes: List[str]
+    expires_at: Optional[datetime] = None
+
+
+class ApiKeyCreateResponse(BaseModel):
+    model_config = _M
+
+    key: ApiKey
+    raw_key: str

aisoc_sdk-4.0.0/tests/__init__.py

@@ -0,0 +1 @@
+

aisoc_sdk-4.0.0/tests/test_client.py

@@ -0,0 +1,186 @@
+"""Unit tests for the aisoc-sdk Python client.
+
+Uses pytest-httpx to intercept outgoing requests — no real server needed.
+"""
+
+from __future__ import annotations
+
+import pytest
+from pytest_httpx import HTTPXMock
+
+from aisoc_sdk import AiSOCClient, AiSOCError
+from aisoc_sdk.models import AlertSeverity, AlertStatus
+
+
+BASE_URL = "https://aisoc.test"
+TOKEN = "aisoc_test_token"
+
+
+# ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+
+@pytest.fixture
+async def client():
+    async with AiSOCClient(base_url=BASE_URL, token=TOKEN) as c:
+        yield c
+
+
+# ─── Alert tests ──────────────────────────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_alerts_list(httpx_mock: HTTPXMock):
+    page_data = {
+        "items": [
+            {
+                "id": "a1",
+                "tenant_id": "t1",
+                "title": "Test Alert",
+                "severity": "critical",
+                "status": "open",
+                "source": "siem",
+                "mitre_tactics": [],
+                "created_at": "2024-01-01T00:00:00Z",
+                "updated_at": "2024-01-01T00:00:00Z",
+            }
+        ],
+        "total": 1,
+        "page": 1,
+        "page_size": 20,
+    }
+    httpx_mock.add_response(json=page_data)
+
+    async with AiSOCClient(base_url=BASE_URL, token=TOKEN) as client:
+        page = await client.alerts.list()
+
+    assert page.total == 1
+    assert page.items[0].id == "a1"
+    assert page.items[0].severity == AlertSeverity.CRITICAL
+
+
+@pytest.mark.asyncio
+async def test_alerts_get(httpx_mock: HTTPXMock):
+    alert_data = {
+        "id": "a42",
+        "tenant_id": "t1",
+        "title": "Critical Alert",
+        "severity": "high",
+        "status": "in_progress",
+        "source": "edr",
+        "mitre_tactics": ["TA0001"],
+        "created_at": "2024-01-01T00:00:00Z",
+        "updated_at": "2024-01-01T00:00:00Z",
+    }
+    httpx_mock.add_response(json=alert_data)
+
+    async with AiSOCClient(base_url=BASE_URL, token=TOKEN) as client:
+        alert = await client.alerts.get("a42")
+
+    assert alert.id == "a42"
+    assert alert.status == AlertStatus.IN_PROGRESS
+
+
+# ─── Case tests ───────────────────────────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_cases_create(httpx_mock: HTTPXMock):
+    case_data = {
+        "id": "c1",
+        "tenant_id": "t1",
+        "case_number": "CASE-001",
+        "title": "Incident",
+        "status": "open",
+        "priority": "high",
+        "mitre_tactics": [],
+        "alert_ids": [],
+        "created_at": "2024-01-01T00:00:00Z",
+        "updated_at": "2024-01-01T00:00:00Z",
+    }
+    httpx_mock.add_response(status_code=201, json=case_data)
+
+    async with AiSOCClient(base_url=BASE_URL, token=TOKEN) as client:
+        case = await client.cases.create(title="Incident", priority="high")
+
+    assert case.id == "c1"
+    assert case.case_number == "CASE-001"
+
+
+@pytest.mark.asyncio
+async def test_a_204_delete_resolves_to_none(httpx_mock: HTTPXMock):
+    """This used to exercise ``cases.delete``.
+
+    That method called a DELETE route the API has never declared, and this
+    test passed anyway because ``httpx_mock`` answers whatever the client
+    asks. Repointed at ``playbooks.delete``, which is a real 204.
+    """
+    httpx_mock.add_response(status_code=204)
+
+    async with AiSOCClient(base_url=BASE_URL, token=TOKEN) as client:
+        result = await client.playbooks.delete("p1")
+
+    assert result is None
+    assert httpx_mock.get_requests()[0].url.path == "/api/v1/playbooks/p1"
+
+
+# ─── Error handling ───────────────────────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_raises_aisoc_error_on_404(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(status_code=404, json={"detail": "Not found"})
+
+    async with AiSOCClient(base_url=BASE_URL, token=TOKEN) as client:
+        with pytest.raises(AiSOCError) as exc_info:
+            await client.alerts.get("missing")
+
+    assert exc_info.value.status_code == 404
+    assert "Not found" in exc_info.value.detail
+
+
+@pytest.mark.asyncio
+async def test_raises_aisoc_error_on_403(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(status_code=403, json={"detail": "Forbidden"})
+
+    async with AiSOCClient(base_url=BASE_URL, token=TOKEN) as client:
+        with pytest.raises(AiSOCError) as exc_info:
+            await client.cases.list()
+
+    assert exc_info.value.status_code == 403
+
+
+# ─── Auth header ─────────────────────────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_bearer_token_is_sent(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(json={"items": [], "total": 0, "page": 1, "page_size": 20})
+
+    async with AiSOCClient(base_url=BASE_URL, token="aisoc_my_secret") as client:
+        await client.alerts.list()
+
+    request = httpx_mock.get_requests()[0]
+    assert request.headers["Authorization"] == "Bearer aisoc_my_secret"
+
+
+# ─── Context manager ─────────────────────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_context_manager_required():
+    client = AiSOCClient(base_url=BASE_URL, token=TOKEN)
+    with pytest.raises(RuntimeError):
+        await client.graphql("{ __typename }")
+
+
+# ─── GraphQL ─────────────────────────────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_graphql_query(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(json={"data": {"__typename": "Query"}})
+
+    async with AiSOCClient(base_url=BASE_URL, token=TOKEN) as client:
+        result = await client.graphql("{ __typename }")
+
+    assert result["data"]["__typename"] == "Query"