hundredflags-sdk 0.4.0__py3-none-any.whl

ai_security_school_sdk/__init__.py

@@ -0,0 +1,62 @@
+"""Compatibility imports; use :mod:`hundredflags_sdk` for new code."""
+
+from hundredflags_sdk import (
+    ActionDescriptor as ActionDescriptor,
+)
+from hundredflags_sdk import (
+    ActionValidationError as ActionValidationError,
+)
+from hundredflags_sdk import (
+    APIError as APIError,
+)
+from hundredflags_sdk import (
+    AsyncClient as AsyncClient,
+)
+from hundredflags_sdk import (
+    AuthenticationError as AuthenticationError,
+)
+from hundredflags_sdk import (
+    Client as Client,
+)
+from hundredflags_sdk import (
+    ConfigurationError as ConfigurationError,
+)
+from hundredflags_sdk import (
+    ConflictError as ConflictError,
+)
+from hundredflags_sdk import (
+    InstanceDocumentation as InstanceDocumentation,
+)
+from hundredflags_sdk import (
+    LimitExceededError as LimitExceededError,
+)
+from hundredflags_sdk import (
+    NotFoundError as NotFoundError,
+)
+from hundredflags_sdk import (
+    PermissionDeniedError as PermissionDeniedError,
+)
+from hundredflags_sdk import (
+    ProtocolError as ProtocolError,
+)
+from hundredflags_sdk import (
+    RuntimeResponse as RuntimeResponse,
+)
+from hundredflags_sdk import (
+    SDKError as SDKError,
+)
+from hundredflags_sdk import (
+    TaskDocumentation as TaskDocumentation,
+)
+from hundredflags_sdk import (
+    TaskSummary as TaskSummary,
+)
+from hundredflags_sdk import (
+    TransportError as TransportError,
+)
+from hundredflags_sdk import (
+    __all__ as __all__,
+)
+from hundredflags_sdk import (
+    __version__ as __version__,
+)

ai_security_school_sdk/async_client.py

@@ -0,0 +1,23 @@
+"""Compatibility imports; use :mod:`hundredflags_sdk.async_client` for new code."""
+
+from hundredflags_sdk.async_client import (
+    AsyncActions as AsyncActions,
+)
+from hundredflags_sdk.async_client import (
+    AsyncClient as AsyncClient,
+)
+from hundredflags_sdk.async_client import (
+    AsyncEnvironmentResource as AsyncEnvironmentResource,
+)
+from hundredflags_sdk.async_client import (
+    AsyncEnvironments as AsyncEnvironments,
+)
+from hundredflags_sdk.async_client import (
+    AsyncEnvironmentTasks as AsyncEnvironmentTasks,
+)
+from hundredflags_sdk.async_client import (
+    AsyncTaskResource as AsyncTaskResource,
+)
+from hundredflags_sdk.async_client import (
+    AsyncTasks as AsyncTasks,
+)

ai_security_school_sdk/client.py

@@ -0,0 +1,23 @@
+"""Compatibility imports; use :mod:`hundredflags_sdk.client` for new code."""
+
+from hundredflags_sdk.client import (
+    Actions as Actions,
+)
+from hundredflags_sdk.client import (
+    Client as Client,
+)
+from hundredflags_sdk.client import (
+    EnvironmentResource as EnvironmentResource,
+)
+from hundredflags_sdk.client import (
+    Environments as Environments,
+)
+from hundredflags_sdk.client import (
+    EnvironmentTasks as EnvironmentTasks,
+)
+from hundredflags_sdk.client import (
+    TaskResource as TaskResource,
+)
+from hundredflags_sdk.client import (
+    Tasks as Tasks,
+)

ai_security_school_sdk/errors.py

@@ -0,0 +1,38 @@
+"""Compatibility imports; use :mod:`hundredflags_sdk.errors` for new code."""
+
+from hundredflags_sdk.errors import (
+    ActionValidationError as ActionValidationError,
+)
+from hundredflags_sdk.errors import (
+    APIError as APIError,
+)
+from hundredflags_sdk.errors import (
+    AuthenticationError as AuthenticationError,
+)
+from hundredflags_sdk.errors import (
+    ConfigurationError as ConfigurationError,
+)
+from hundredflags_sdk.errors import (
+    ConflictError as ConflictError,
+)
+from hundredflags_sdk.errors import (
+    LimitExceededError as LimitExceededError,
+)
+from hundredflags_sdk.errors import (
+    NotFoundError as NotFoundError,
+)
+from hundredflags_sdk.errors import (
+    PermissionDeniedError as PermissionDeniedError,
+)
+from hundredflags_sdk.errors import (
+    ProtocolError as ProtocolError,
+)
+from hundredflags_sdk.errors import (
+    SDKError as SDKError,
+)
+from hundredflags_sdk.errors import (
+    TransportError as TransportError,
+)
+from hundredflags_sdk.errors import (
+    api_error as api_error,
+)

ai_security_school_sdk/models.py

@@ -0,0 +1,26 @@
+"""Compatibility imports; use :mod:`hundredflags_sdk.models` for new code."""
+
+from hundredflags_sdk.models import (
+    ActionDescriptor as ActionDescriptor,
+)
+from hundredflags_sdk.models import (
+    InstanceDocumentation as InstanceDocumentation,
+)
+from hundredflags_sdk.models import (
+    InstanceList as InstanceList,
+)
+from hundredflags_sdk.models import (
+    JsonObject as JsonObject,
+)
+from hundredflags_sdk.models import (
+    PublicModel as PublicModel,
+)
+from hundredflags_sdk.models import (
+    RuntimeResponse as RuntimeResponse,
+)
+from hundredflags_sdk.models import (
+    TaskDocumentation as TaskDocumentation,
+)
+from hundredflags_sdk.models import (
+    TaskSummary as TaskSummary,
+)

hundredflags_sdk/__init__.py

@@ -0,0 +1,49 @@
+"""HundredFlags SDK: documentation and actions for existing agent environments."""
+
+from importlib.metadata import version as _package_version
+
+from .async_client import AsyncClient
+from .client import Client
+from .errors import (
+    ActionValidationError,
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    ConflictError,
+    LimitExceededError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProtocolError,
+    SDKError,
+    TransportError,
+)
+from .models import (
+    ActionDescriptor,
+    InstanceDocumentation,
+    RuntimeResponse,
+    TaskDocumentation,
+    TaskSummary,
+)
+
+__version__ = _package_version("hundredflags-sdk")
+
+__all__ = [
+    "APIError",
+    "ActionDescriptor",
+    "ActionValidationError",
+    "AsyncClient",
+    "AuthenticationError",
+    "Client",
+    "ConfigurationError",
+    "ConflictError",
+    "InstanceDocumentation",
+    "LimitExceededError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "ProtocolError",
+    "RuntimeResponse",
+    "SDKError",
+    "TaskDocumentation",
+    "TaskSummary",
+    "TransportError",
+]

hundredflags_sdk/_handles.py

@@ -0,0 +1,34 @@
+"""Shared metadata properties; resources do not represent separate server sessions."""
+
+from .models import InstanceDocumentation, TaskDocumentation, TaskSummary
+
+
+class EnvironmentHandle:
+    def __init__(self, info: InstanceDocumentation) -> None:
+        self.info = info
+
+    @property
+    def instance_id(self) -> str:
+        return self.info.instance_id
+
+    @property
+    def title(self) -> str:
+        return self.info.title
+
+
+class TaskHandle:
+    def __init__(self, info: TaskSummary | TaskDocumentation, instance_id: str) -> None:
+        self.info = info
+        self._instance_id = instance_id
+
+    @property
+    def task_id(self) -> str:
+        return self.info.task_id
+
+    @property
+    def instance_id(self) -> str:
+        return self._instance_id
+
+    @property
+    def title(self) -> str:
+        return self.info.title

hundredflags_sdk/_http.py

@@ -0,0 +1,135 @@
+"""Transport policy and response parsing shared by synchronous and async clients."""
+
+import math
+import os
+import re
+from importlib.metadata import version
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+from pydantic import ValidationError
+
+from .errors import ConfigurationError, ProtocolError, api_error
+from .models import JsonObject, PublicModel
+
+DEFAULT_BASE_URL = "https://plgn.hundredflags.ru"
+API_PREFIX = "/api/agent-env/"
+RETRYABLE_STATUS = {429, 502, 503, 504}
+
+
+def identifier(value: str) -> str:
+    if not isinstance(value, str) or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.:-]*", value):
+        raise ConfigurationError("Resource identifiers must contain only letters, digits, _ . : -")
+    return value
+
+
+def positive_duration(value: float, name: str, *, allow_zero: bool = False) -> float:
+    if not math.isfinite(value) or value < 0 or (value == 0 and not allow_zero):
+        raise ConfigurationError(
+            f"{name} must be finite and {'non-negative' if allow_zero else 'positive'}"
+        )
+    return value
+
+
+def environment_config(overrides: dict[str, Any]) -> dict[str, Any]:
+    options: dict[str, Any] = {
+        "token": os.environ.get(
+            "HUNDREDFLAGS_TOKEN", os.environ.get("AI_SECURITY_SCHOOL_TOKEN", "")
+        ),
+        "base_url": os.environ.get(
+            "HUNDREDFLAGS_BASE_URL",
+            os.environ.get("AI_SECURITY_SCHOOL_BASE_URL") or DEFAULT_BASE_URL,
+        ),
+    }
+    options.update(overrides)
+    return options
+
+
+def client_options(
+    token: str, base_url: str, timeout: float, max_retries: int, retry_backoff: float
+) -> dict[str, Any]:
+    if not token or token != token.strip() or any(ord(c) < 33 or ord(c) > 126 for c in token):
+        raise ConfigurationError("Set HUNDREDFLAGS_TOKEN to a valid learner token")
+    try:
+        url = urlsplit(base_url)
+    except ValueError as exc:
+        raise ConfigurationError("base_url must be a valid server URL") from exc
+    if (
+        url.scheme not in {"https", "http"}
+        or not url.netloc
+        or url.username is not None
+        or url.password is not None
+        or url.query
+        or url.fragment
+        or url.path.rstrip("/") not in {"", API_PREFIX.rstrip("/")}
+    ):
+        raise ConfigurationError("base_url must be a server origin or agent-env API base URL")
+    if url.scheme == "http" and url.hostname not in {"localhost", "127.0.0.1", "::1", "testserver"}:
+        raise ConfigurationError(
+            "Remote servers require HTTPS; HTTP is supported only for local use"
+        )
+    positive_duration(timeout, "timeout")
+    positive_duration(retry_backoff, "retry_backoff", allow_zero=True)
+    if not isinstance(max_retries, int) or isinstance(max_retries, bool) or max_retries < 0:
+        raise ConfigurationError("max_retries must be a non-negative integer")
+    return {
+        "base_url": f"{url.scheme}://{url.netloc}{API_PREFIX}",
+        "headers": {
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/json",
+            "User-Agent": f"hundredflags-sdk/{version('hundredflags-sdk')}",
+        },
+        "timeout": timeout,
+        "follow_redirects": False,
+    }
+
+
+def retry_delay(response: httpx.Response | None, attempt: int, backoff: float) -> float:
+    if response is not None:
+        try:
+            delay = float(response.headers.get("Retry-After", ""))
+            if math.isfinite(delay) and delay >= 0:
+                return min(delay, 30.0)
+        except ValueError:
+            pass
+    return min(math.ldexp(backoff, min(attempt, 10)), 30.0)
+
+
+def decode_response(response: httpx.Response) -> JsonObject:
+    if not 200 <= response.status_code < 300:
+        try:
+            body = response.json()
+        except ValueError:
+            body = {}
+        if not isinstance(body, dict):
+            body = {}
+        error = body.get("error")
+        error = error if isinstance(error, dict) else {}
+        code = error.get("code")
+        message = error.get("message")
+        details = error.get("details")
+        details = dict(details) if isinstance(details, dict) else {}
+        for key in ("usage", "retry_after"):
+            if key in body:
+                details[key] = body[key]
+        raise api_error(
+            code if isinstance(code, str) else "http_error",
+            message if isinstance(message, str) else f"Server returned HTTP {response.status_code}",
+            status_code=response.status_code,
+            details=details,
+        )
+    try:
+        value = response.json()
+    except ValueError as exc:
+        raise ProtocolError("Server returned invalid JSON") from exc
+    if not isinstance(value, dict):
+        raise ProtocolError("Expected a JSON object response")
+    return value
+
+
+def parse_model[ModelT: PublicModel](model: type[ModelT], value: JsonObject) -> ModelT:
+    try:
+        return model.model_validate(value)
+    except ValidationError as exc:
+        raise ProtocolError(f"Server returned an invalid {model.__name__} response") from exc

hundredflags_sdk/_schema.py

@@ -0,0 +1,71 @@
+"""Local schema validation never resolves or downloads remote references."""
+
+import json
+from typing import Any
+
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import SchemaError
+from referencing import Registry
+
+from .errors import ActionValidationError, ProtocolError
+from .models import JsonObject, TaskDocumentation
+
+
+def _check_references(value: Any) -> None:
+    if isinstance(value, dict):
+        for key, child in value.items():
+            if key in {"$ref", "$dynamicRef"} and (
+                not isinstance(child, str) or not child.startswith("#")
+            ):
+                raise ProtocolError("Action schemas may only use local fragment references")
+            _check_references(child)
+    elif isinstance(value, list):
+        for child in value:
+            _check_references(child)
+
+
+def json_object(value: JsonObject) -> JsonObject:
+    if not isinstance(value, dict):
+        raise ActionValidationError("Action payload must be a JSON object")
+    try:
+        frozen: JsonObject = json.loads(json.dumps(value, allow_nan=False))
+    except (TypeError, ValueError, OverflowError, RecursionError) as exc:
+        raise ActionValidationError("Action payload must contain only finite JSON values") from exc
+    return frozen
+
+
+def validate_payload(
+    schema: JsonObject, payload: JsonObject, *, name: str = "action"
+) -> JsonObject:
+    frozen = json_object(payload)
+    _check_references(schema)
+    try:
+        Draft202012Validator.check_schema(schema)
+        validator = Draft202012Validator(schema, registry=Registry())
+        violation = next(validator.iter_errors(frozen), None)
+    except SchemaError as exc:
+        raise ProtocolError("Server returned an invalid action input schema") from exc
+    except Exception as exc:
+        raise ProtocolError("Action input schema contains an unresolvable reference") from exc
+    if violation is not None:
+        path = list(violation.absolute_path)
+        location = ".".join(str(part) for part in path) or "payload"
+        raise ActionValidationError(
+            f"{name}: {location} fails {violation.validator} validation", path=path
+        )
+    return frozen
+
+
+def action_payload(
+    documentation: TaskDocumentation, name: str, arguments: JsonObject
+) -> JsonObject:
+    descriptor = next((action for action in documentation.actions if action.name == name), None)
+    if descriptor is None:
+        raise ActionValidationError("This action is not documented for the task")
+    arguments = json_object(arguments)
+    if "action" in arguments:
+        raise ActionValidationError("Pass the action name separately, without arguments.action")
+    validated = validate_payload(descriptor.input_schema, arguments, name=name)
+    return validate_payload(
+        documentation.action_payload_schema, {"action": name, **validated}, name=name
+    )

hundredflags_sdk/async_client.py

@@ -0,0 +1,226 @@
+"""Asynchronous client for the platform's shared agent-env runtime."""
+
+import asyncio
+from types import TracebackType
+from typing import Any, Self
+
+import httpx
+
+from ._handles import EnvironmentHandle, TaskHandle
+from ._http import (
+    DEFAULT_BASE_URL,
+    RETRYABLE_STATUS,
+    client_options,
+    decode_response,
+    environment_config,
+    identifier,
+    parse_model,
+    retry_delay,
+)
+from ._schema import action_payload, json_object, validate_payload
+from .errors import ActionValidationError, ConfigurationError, ProtocolError, TransportError
+from .models import (
+    ActionDescriptor,
+    InstanceDocumentation,
+    InstanceList,
+    JsonObject,
+    RuntimeResponse,
+    TaskDocumentation,
+    TaskSummary,
+)
+
+
+class AsyncClient:
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 120.0,
+        max_retries: int = 2,
+        retry_backoff: float = 0.25,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        options = client_options(token, base_url, timeout, max_retries, retry_backoff)
+        self._http = httpx.AsyncClient(**options, transport=transport)
+        self._max_retries = max_retries
+        self._retry_backoff = retry_backoff
+        self.envs = AsyncEnvironments(self)
+        self.tasks = AsyncTasks(self)
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> Self:
+        return cls(**environment_config(overrides))
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: JsonObject | None = None,
+        params: dict[str, str] | None = None,
+    ) -> JsonObject:
+        # The shared runtime does not deduplicate mutations. Never retry a POST.
+        retries = self._max_retries if method == "GET" else 0
+        for attempt in range(retries + 1):
+            response: httpx.Response | None = None
+            try:
+                response = await self._http.request(method, path, json=body, params=params)
+            except httpx.TransportError as exc:
+                if attempt == retries:
+                    raise TransportError(may_have_executed=method != "GET") from exc
+            else:
+                if response.status_code not in RETRYABLE_STATUS or attempt == retries:
+                    return decode_response(response)
+            await asyncio.sleep(retry_delay(response, attempt, self._retry_backoff))
+        raise AssertionError("Unreachable retry state")
+
+
+class AsyncEnvironments:
+    def __init__(self, client: AsyncClient) -> None:
+        self._client = client
+
+    async def get(self, instance_id: str) -> "AsyncEnvironmentResource":
+        data = await self._client._request("GET", f"instances/{identifier(instance_id)}")
+        info = parse_model(InstanceDocumentation, data)
+        if info.instance_id != instance_id:
+            raise ProtocolError("Server returned documentation for a different environment")
+        return AsyncEnvironmentResource(self._client, info)
+
+    async def list(self) -> list["AsyncEnvironmentResource"]:
+        data = parse_model(InstanceList, await self._client._request("GET", "instances"))
+        return [AsyncEnvironmentResource(self._client, info) for info in data.instances]
+
+
+class AsyncTasks:
+    def __init__(self, client: AsyncClient) -> None:
+        self._client = client
+
+    async def get(self, task_id: str) -> "AsyncTaskResource":
+        data = await self._client._request("GET", f"tasks/{identifier(task_id)}/documentation")
+        info = parse_model(TaskDocumentation, data)
+        if info.task_id != task_id:
+            raise ProtocolError("Server returned documentation for a different task")
+        return AsyncTaskResource(self._client, info, info.instance_id)
+
+
+class AsyncEnvironmentResource(EnvironmentHandle):
+    def __init__(self, client: AsyncClient, info: InstanceDocumentation) -> None:
+        super().__init__(info)
+        self.tasks = AsyncEnvironmentTasks(client, info)
+
+
+class AsyncEnvironmentTasks:
+    def __init__(self, client: AsyncClient, info: InstanceDocumentation) -> None:
+        self._client = client
+        self._info = info
+
+    async def list(self) -> list["AsyncTaskResource"]:
+        """Return handles from the environment snapshot; load task schemas on use."""
+        return [
+            AsyncTaskResource(self._client, task, self._info.instance_id)
+            for task in self._info.tasks
+        ]
+
+    async def get(self, task_id: str) -> "AsyncTaskResource":
+        if not any(task.task_id == task_id for task in self._info.tasks):
+            raise ConfigurationError("The task is not in this environment's documentation")
+        task = await self._client.tasks.get(task_id)
+        if task.instance_id != self._info.instance_id:
+            raise ProtocolError("Server returned documentation for a different environment")
+        return task
+
+
+class AsyncTaskResource(TaskHandle):
+    def __init__(
+        self, client: AsyncClient, info: TaskSummary | TaskDocumentation, instance_id: str
+    ) -> None:
+        super().__init__(info, instance_id)
+        self._client = client
+        self.actions = AsyncActions(self)
+
+    async def documentation(self) -> TaskDocumentation:
+        """Fetch current learner documentation and refresh this resource's metadata."""
+        data = await self._client._request("GET", f"tasks/{identifier(self.task_id)}/documentation")
+        info = parse_model(TaskDocumentation, data)
+        if info.task_id != self.task_id or info.instance_id != self.instance_id:
+            raise ProtocolError("Server returned documentation for a different task or environment")
+        self.info = info
+        return info
+
+    async def state(self) -> RuntimeResponse:
+        return parse_model(
+            RuntimeResponse,
+            await self._client._request(
+                "GET", "state", params={"task_id": identifier(self.task_id)}
+            ),
+        )
+
+    async def act(self, payload: JsonObject) -> RuntimeResponse:
+        """Send the task's native payload, including chat schemas without an action name."""
+        documentation = await self.documentation()
+        return await self._act(validate_payload(documentation.action_payload_schema, payload))
+
+    async def _act(self, payload: JsonObject) -> RuntimeResponse:
+        return parse_model(
+            RuntimeResponse,
+            await self._client._request(
+                "POST",
+                "action",
+                body={"task_id": identifier(self.task_id), "action_payload": payload},
+            ),
+        )
+
+    async def grade(self, payload: JsonObject | None = None) -> RuntimeResponse:
+        validated = json_object(payload if payload is not None else {})
+        if not (await self.documentation()).supports_standalone_grading:
+            raise ActionValidationError(
+                "Standalone grading is unavailable; inspect the task's documented actions"
+            )
+        return parse_model(
+            RuntimeResponse,
+            await self._client._request(
+                "POST",
+                "grade",
+                body={
+                    "task_id": identifier(self.task_id),
+                    "payload": validated,
+                },
+            ),
+        )
+
+    async def reset(self) -> RuntimeResponse:
+        """Reset the user's shared environment through the task's existing reset behavior."""
+        return parse_model(
+            RuntimeResponse,
+            await self._client._request(
+                "POST", "reset", body={"task_id": identifier(self.task_id)}
+            ),
+        )
+
+
+class AsyncActions:
+    def __init__(self, task: AsyncTaskResource) -> None:
+        self._task = task
+
+    async def list(self) -> list[ActionDescriptor]:
+        return (await self._task.documentation()).actions
+
+    async def call(self, name: str, arguments: JsonObject) -> RuntimeResponse:
+        """Validate documented arguments and insert the native action discriminator."""
+        documentation = await self._task.documentation()
+        return await self._task._act(action_payload(documentation, name, arguments))

hundredflags_sdk/client.py

@@ -0,0 +1,221 @@
+"""Synchronous client for the platform's shared agent-env runtime."""
+
+import time
+from types import TracebackType
+from typing import Any, Self
+
+import httpx
+
+from ._handles import EnvironmentHandle, TaskHandle
+from ._http import (
+    DEFAULT_BASE_URL,
+    RETRYABLE_STATUS,
+    client_options,
+    decode_response,
+    environment_config,
+    identifier,
+    parse_model,
+    retry_delay,
+)
+from ._schema import action_payload, json_object, validate_payload
+from .errors import ActionValidationError, ConfigurationError, ProtocolError, TransportError
+from .models import (
+    ActionDescriptor,
+    InstanceDocumentation,
+    InstanceList,
+    JsonObject,
+    RuntimeResponse,
+    TaskDocumentation,
+    TaskSummary,
+)
+
+
+class Client:
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 120.0,
+        max_retries: int = 2,
+        retry_backoff: float = 0.25,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        options = client_options(token, base_url, timeout, max_retries, retry_backoff)
+        self._http = httpx.Client(**options, transport=transport)
+        self._max_retries = max_retries
+        self._retry_backoff = retry_backoff
+        self.envs = Environments(self)
+        self.tasks = Tasks(self)
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> Self:
+        return cls(**environment_config(overrides))
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: JsonObject | None = None,
+        params: dict[str, str] | None = None,
+    ) -> JsonObject:
+        # The shared runtime does not deduplicate mutations. Never retry a POST.
+        retries = self._max_retries if method == "GET" else 0
+        for attempt in range(retries + 1):
+            response: httpx.Response | None = None
+            try:
+                response = self._http.request(method, path, json=body, params=params)
+            except httpx.TransportError as exc:
+                if attempt == retries:
+                    raise TransportError(may_have_executed=method != "GET") from exc
+            else:
+                if response.status_code not in RETRYABLE_STATUS or attempt == retries:
+                    return decode_response(response)
+            time.sleep(retry_delay(response, attempt, self._retry_backoff))
+        raise AssertionError("Unreachable retry state")
+
+
+class Environments:
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def get(self, instance_id: str) -> "EnvironmentResource":
+        data = self._client._request("GET", f"instances/{identifier(instance_id)}")
+        info = parse_model(InstanceDocumentation, data)
+        if info.instance_id != instance_id:
+            raise ProtocolError("Server returned documentation for a different environment")
+        return EnvironmentResource(self._client, info)
+
+    def list(self) -> list["EnvironmentResource"]:
+        data = parse_model(InstanceList, self._client._request("GET", "instances"))
+        return [EnvironmentResource(self._client, info) for info in data.instances]
+
+
+class Tasks:
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def get(self, task_id: str) -> "TaskResource":
+        data = self._client._request("GET", f"tasks/{identifier(task_id)}/documentation")
+        info = parse_model(TaskDocumentation, data)
+        if info.task_id != task_id:
+            raise ProtocolError("Server returned documentation for a different task")
+        return TaskResource(self._client, info, info.instance_id)
+
+
+class EnvironmentResource(EnvironmentHandle):
+    def __init__(self, client: Client, info: InstanceDocumentation) -> None:
+        super().__init__(info)
+        self.tasks = EnvironmentTasks(client, info)
+
+
+class EnvironmentTasks:
+    def __init__(self, client: Client, info: InstanceDocumentation) -> None:
+        self._client = client
+        self._info = info
+
+    def list(self) -> list["TaskResource"]:
+        """Return handles from the environment snapshot; load task schemas on use."""
+        return [
+            TaskResource(self._client, task, self._info.instance_id) for task in self._info.tasks
+        ]
+
+    def get(self, task_id: str) -> "TaskResource":
+        if not any(task.task_id == task_id for task in self._info.tasks):
+            raise ConfigurationError("The task is not in this environment's documentation")
+        task = self._client.tasks.get(task_id)
+        if task.instance_id != self._info.instance_id:
+            raise ProtocolError("Server returned documentation for a different environment")
+        return task
+
+
+class TaskResource(TaskHandle):
+    def __init__(
+        self, client: Client, info: TaskSummary | TaskDocumentation, instance_id: str
+    ) -> None:
+        super().__init__(info, instance_id)
+        self._client = client
+        self.actions = Actions(self)
+
+    def documentation(self) -> TaskDocumentation:
+        """Fetch current learner documentation and refresh this resource's metadata."""
+        data = self._client._request("GET", f"tasks/{identifier(self.task_id)}/documentation")
+        info = parse_model(TaskDocumentation, data)
+        if info.task_id != self.task_id or info.instance_id != self.instance_id:
+            raise ProtocolError("Server returned documentation for a different task or environment")
+        self.info = info
+        return info
+
+    def state(self) -> RuntimeResponse:
+        return parse_model(
+            RuntimeResponse,
+            self._client._request("GET", "state", params={"task_id": identifier(self.task_id)}),
+        )
+
+    def act(self, payload: JsonObject) -> RuntimeResponse:
+        """Send the task's native payload, including chat schemas without an action name."""
+        documentation = self.documentation()
+        return self._act(validate_payload(documentation.action_payload_schema, payload))
+
+    def _act(self, payload: JsonObject) -> RuntimeResponse:
+        return parse_model(
+            RuntimeResponse,
+            self._client._request(
+                "POST",
+                "action",
+                body={"task_id": identifier(self.task_id), "action_payload": payload},
+            ),
+        )
+
+    def grade(self, payload: JsonObject | None = None) -> RuntimeResponse:
+        validated = json_object(payload if payload is not None else {})
+        if not self.documentation().supports_standalone_grading:
+            raise ActionValidationError(
+                "Standalone grading is unavailable; inspect the task's documented actions"
+            )
+        return parse_model(
+            RuntimeResponse,
+            self._client._request(
+                "POST",
+                "grade",
+                body={
+                    "task_id": identifier(self.task_id),
+                    "payload": validated,
+                },
+            ),
+        )
+
+    def reset(self) -> RuntimeResponse:
+        """Reset the user's shared environment through the task's existing reset behavior."""
+        return parse_model(
+            RuntimeResponse,
+            self._client._request("POST", "reset", body={"task_id": identifier(self.task_id)}),
+        )
+
+
+class Actions:
+    def __init__(self, task: TaskResource) -> None:
+        self._task = task
+
+    def list(self) -> list[ActionDescriptor]:
+        return self._task.documentation().actions
+
+    def call(self, name: str, arguments: JsonObject) -> RuntimeResponse:
+        """Validate documented arguments and insert the native action discriminator."""
+        documentation = self._task.documentation()
+        return self._task._act(action_payload(documentation, name, arguments))

hundredflags_sdk/errors.py

@@ -0,0 +1,89 @@
+"""SDK failures omit authentication headers and locally supplied payloads."""
+
+from typing import Any
+
+
+class SDKError(Exception):
+    """Base class for SDK failures."""
+
+
+class ConfigurationError(SDKError, ValueError):
+    pass
+
+
+class ProtocolError(SDKError):
+    """The server returned an invalid response or unsupported JSON schema."""
+
+
+class ActionValidationError(SDKError, ValueError):
+    """Arguments do not satisfy the task's documented action schema."""
+
+    def __init__(self, message: str, *, path: list[str | int] | None = None) -> None:
+        super().__init__(message)
+        self.path = path or []
+
+
+class APIError(SDKError):
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        status_code: int,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        self.details = details or {}
+        usage = self.details.get("usage")
+        self.usage: dict[str, Any] | None = usage if isinstance(usage, dict) else None
+
+
+class AuthenticationError(APIError):
+    pass
+
+
+class PermissionDeniedError(APIError):
+    pass
+
+
+class NotFoundError(APIError):
+    pass
+
+
+class ConflictError(APIError):
+    pass
+
+
+class LimitExceededError(APIError):
+    pass
+
+
+class TransportError(SDKError):
+    """No definitive response was received; a mutation may already have executed."""
+
+    def __init__(self, *, may_have_executed: bool) -> None:
+        message = "Unable to obtain a definitive server response."
+        if may_have_executed:
+            message += " The action may have executed; inspect task.state() before retrying."
+        super().__init__(message)
+        self.may_have_executed = may_have_executed
+
+
+def api_error(
+    code: str,
+    message: str,
+    *,
+    status_code: int,
+    details: dict[str, Any] | None = None,
+) -> APIError:
+    cls: type[APIError] = {
+        401: AuthenticationError,
+        403: PermissionDeniedError,
+        404: NotFoundError,
+        409: ConflictError,
+        429: LimitExceededError,
+    }.get(status_code, APIError)
+    return cls(code, message, status_code=status_code, details=details)

hundredflags_sdk/models.py

@@ -0,0 +1,64 @@
+"""Documentation and responses from the shared agent-env API."""
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+JsonObject = dict[str, Any]
+
+
+class PublicModel(BaseModel):
+    """Preserve additive server fields as data, never executable behavior."""
+
+    model_config = ConfigDict(extra="allow")
+
+
+class ActionDescriptor(PublicModel):
+    name: str
+    description: str
+    input_schema: JsonObject
+    examples: list[JsonObject] = Field(default_factory=list)
+
+
+class TaskSummary(PublicModel):
+    task_id: str
+    ctf_ref: str
+    title: str
+
+
+class InstanceDocumentation(PublicModel):
+    instance_id: str
+    agent_env_ref: str
+    title: str
+    description: str
+    tasks: list[TaskSummary]
+
+
+class InstanceList(PublicModel):
+    instances: list[InstanceDocumentation]
+
+
+class TaskDocumentation(TaskSummary):
+    instance_id: str
+    agent_env_ref: str
+    description: str
+    instructions: str
+    action_payload_schema: JsonObject
+    action_payload_examples: list[JsonObject] = Field(default_factory=list)
+    actions: list[ActionDescriptor] = Field(default_factory=list)
+    supports_grading: bool
+    supports_standalone_grading: bool
+
+
+class RuntimeResponse(PublicModel):
+    status: str
+    agent_env_ref: str | None = None
+    ctf_ref: str | None = None
+    state: JsonObject | None = None
+    response: JsonObject | None = None
+    completed: bool | None = None
+    grader_passed: bool | None = None
+    grader_result: JsonObject | None = None
+    missing_prerequisites: list[JsonObject] | None = None
+    usage: JsonObject | None = None
+    message: str | None = None

hundredflags_sdk-0.4.0.dist-info/METADATA

@@ -0,0 +1,240 @@
+Metadata-Version: 2.3
+Name: hundredflags-sdk
+Version: 0.4.0
+Summary: Python client for HundredFlags agent environment documentation and actions
+Author: germankochnev
+Author-email: germankochnev <kochgerm@gmail.com>
+Requires-Dist: httpx>=0.28,<1
+Requires-Dist: pydantic>=2.10,<3
+Requires-Dist: jsonschema>=4.23,<5
+Requires-Dist: referencing>=0.35,<1
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/ai-security-lab-itmo/hundredflags-sdk
+Project-URL: Documentation, https://github.com/ai-security-lab-itmo/hundredflags-sdk#readme
+Project-URL: Issues, https://github.com/ai-security-lab-itmo/hundredflags-sdk/issues
+Description-Content-Type: text/markdown
+
+# HundredFlags SDK
+
+Python-клиент для работы с агентными средами полигона HundredFlags.
+SDK получает документацию конкретной задачи и вызывает тот же `agent-env` API,
+которым пользуется браузер: состояние, действия, проверку и сброс.
+
+## Установка
+
+Требуется Python 3.12 или новее.
+
+```sh
+python -m pip install hundredflags-sdk
+```
+
+Для воспроизводимой установки этой версии:
+
+```sh
+python -m pip install hundredflags-sdk==0.4.0
+```
+
+Версия 0.4.0 использует контракт платформы `2026-09-runtime-1` и работает с
+существующими экземплярами `agent-env` и их задачами. Обновляйте SDK вместе с
+платформой; отдельные лаборатории или прогоны создавать не нужно.
+
+## Переход с ai-security-school-sdk
+
+Начиная с 0.4.0 пакет называется `hundredflags-sdk`, а основной импорт —
+`hundredflags_sdk`. API задач и контракт `2026-09-runtime-1` сохранены.
+
+Для перехода из существующего окружения:
+
+```sh
+python -m pip uninstall ai-security-school-sdk
+python -m pip install --upgrade hundredflags-sdk
+```
+
+Удалите старую зависимость из `pyproject.toml` или `requirements.txt`, заменив
+её на `hundredflags-sdk`. Не устанавливайте оба дистрибутива одновременно:
+они содержат общий совместимый модуль `ai_security_school_sdk`.
+Старые импорты клиентов, моделей и исключений продолжают работать через этот
+модуль; реализация у него общая с `hundredflags_sdk`.
+
+`AI_SECURITY_SCHOOL_TOKEN` и `AI_SECURITY_SCHOOL_BASE_URL` остаются совместимыми
+именами переменных окружения. `HUNDREDFLAGS_TOKEN` и `HUNDREDFLAGS_BASE_URL`
+имеют приоритет, когда заданы; аргументы `from_env(...)` имеют приоритет над ними.
+
+## Подключение и документация
+
+На странице операции откройте инструкцию подключения. Создайте временный API-ключ
+в личном кабинете платформы и передайте его через переменную окружения. Ключ
+принадлежит вашему аккаунту и работает со всеми доступными вам задачами;
+конкретную задачу выбирайте по её `task_id` в SDK.
+`HUNDREDFLAGS_BASE_URL` можно задать для другого развёртывания; по умолчанию
+используется `https://plgn.hundredflags.ru`.
+
+```sh
+export HUNDREDFLAGS_TOKEN="YOUR_TOKEN"
+```
+
+```python
+from hundredflags_sdk import Client
+
+with Client.from_env() as client:
+    for env in client.envs.list():
+        print(env.instance_id, env.title)
+        for task in env.tasks.list():
+            print(task.task_id, task.title)
+
+    task = client.tasks.get("YOUR_TASK_ID")
+    docs = task.documentation()
+    print(docs.instructions)
+    print(docs.action_payload_schema)
+    print(docs.action_payload_examples)
+    for action in docs.actions:
+        print(action.name, action.description, action.input_schema, action.examples)
+```
+
+`client.envs.get(instance_id)` возвращает одну среду. `env.tasks.list()` возвращает
+задачи из полученного списка; `env.tasks.get(task_id)` загружает документацию
+выбранной задачи. Среда соответствует `agent-env-instance`, задача —
+`ctf-instance`. Документация описывает доступные студенту точки входа, а не
+внутренние инструменты агента. Набор действий и схемы приходят с сервера, поэтому
+новая задача не требует новой версии SDK.
+
+## Выполнение действий
+
+Для действия с именем используйте `task.actions.call(name, arguments)`.
+Имя и аргументы выбираются из документации конкретной задачи:
+
+```python
+with Client.from_env() as client:
+    task = client.tasks.get("YOUR_TASK_ID")
+    print(task.actions.list())
+
+    # Используйте это имя только если оно есть в документации выбранной задачи.
+    result = task.actions.call("send_message", {"message": "Проверь новый документ"})
+    print(result.status, result.response, result.state)
+    print(task.state().model_dump())
+```
+
+Метод вставляет поле `action` в тело запроса. В `arguments` передаются остальные
+поля; `input_schema` и `examples` описанного действия не содержат `action`.
+SDK проверяет аргументы и полное тело по JSON Schema перед отправкой. Сервер
+применяет проверки существующего обработчика действия, а также контролирует
+доступ, пререквизиты и бюджет пользователя.
+
+`task.act(payload)` принимает полное нативное тело действия. Так поддерживаются
+и существующие среды, у которых нет именованных действий, например чат:
+
+```python
+with Client.from_env() as client:
+    task = client.tasks.get("YOUR_CHAT_TASK_ID")
+    docs = task.documentation()
+    print(docs.action_payload_schema, docs.action_payload_examples)
+    result = task.act({"message": "Привет"})
+    print(result.model_dump())
+```
+
+Пустой `docs.actions` не означает отсутствие возможностей: используйте полную
+схему `action_payload_schema`. SDK не угадывает имена действий по коду runtime.
+Документация не исполняется как Python-код, внешние ссылки JSON Schema не
+загружаются. Внешние поверхности сценария, например MCP-сервис или реестр
+зависимостей, используются через их собственные интерфейсы.
+
+## Состояние, проверка и сброс
+
+```python
+with Client.from_env() as client:
+    task = client.tasks.get("YOUR_TASK_ID")
+    current = task.state()
+    print(current.status, current.missing_prerequisites)
+
+    if task.documentation().supports_standalone_grading:
+        verdict = task.grade()
+        print(verdict.grader_passed, verdict.grader_result, verdict.completed)
+
+    # При необходимости передайте task.grade({...}) полезную нагрузку проверки.
+    # Явный сброс через существующее поведение среды:
+    # task.reset()
+```
+
+`supports_grading` означает наличие оценивания вообще; `supports_standalone_grading`
+разрешает отдельный вызов `grade()`. Некоторые задания оценивают ответ внутри
+своих действий, например `submit_card` или `submit_finding`.
+
+У одного пользователя задачи одной среды разделяют состояние с браузером и
+другими скриптами. Получение нового handle или создание второго клиента не
+создаёт отдельную попытку. Сброс затрагивает общее состояние среды; сохранение
+зачётов и пререквизитов определяется её существующим поведением. Локальный
+контекстный менеджер закрывает только HTTP-соединения.
+
+Алгоритм атаки работает в вашем Python-процессе. Вызовы возвращают обычные ответы
+runtime без фоновых заданий SDK, checkpoint, fork или воспроизведения сценария.
+Вызовы одной среды выполняйте последовательно: параллельные кандидаты будут
+менять одно состояние. Async-клиент удобен для неблокирующего ожидания и работы
+с разными независимыми средами.
+
+## Async
+
+```python
+import asyncio
+from hundredflags_sdk import AsyncClient
+
+
+async def main():
+    async with AsyncClient.from_env() as client:
+        task = await client.tasks.get("YOUR_TASK_ID")
+        docs = await task.documentation()
+        print(docs.instructions)
+        result = await task.act({"message": "Привет"})  # Если разрешено схемой.
+        print(result.response)
+        print((await task.state()).state)
+
+
+asyncio.run(main())
+```
+
+Методы async-ресурсов, включая `env.tasks.list()`, вызываются через `await`.
+Конструкторы, `from_env()`, поля `.info`, `.task_id`, `.instance_id` и `.title`
+синхронные. `task.documentation()` обновляет снимок `.info`; `task.state()`
+получает текущее серверное состояние. Дополнительные поля ответов сохраняются
+в моделях и доступны через `model_dump()`.
+
+Примеры: [документация и вызов](https://github.com/ai-security-lab-itmo/hundredflags-sdk/blob/v0.4.0/examples/first_experiment.py),
+[последовательный поиск кандидатов](https://github.com/ai-security-lab-itmo/hundredflags-sdk/blob/v0.4.0/examples/async_search.py),
+[связанные задачи одной среды](https://github.com/ai-security-lab-itmo/hundredflags-sdk/blob/v0.4.0/examples/multistage.py).
+
+## Ошибки и сетевые повторы
+
+- `APIError` содержит `code`, `message`, `status_code`, `details` и `usage`.
+  Для HTTP 401/403/404/409/429 используются `AuthenticationError`,
+  `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `LimitExceededError`.
+- Успешный HTTP-ответ с `status="locked"` остаётся `RuntimeResponse`:
+  проверьте `status` и `missing_prerequisites` перед дальнейшими действиями.
+- `ActionValidationError` означает локальное несоответствие схеме,
+  `ProtocolError` — некорректный ответ или неподдерживаемую ссылку в схеме.
+- Автоматические повторы допускаются только для GET: при сетевых ошибках и
+  HTTP 429/502/503/504. Параметры клиента: `timeout=120`, `max_retries=2`,
+  `retry_backoff=0.25`; `max_retries=0` отключает повторы.
+- Действия, проверка и сброс **никогда не повторяются автоматически**.
+  При сетевом сбое `TransportError.may_have_executed` показывает, что изменение
+  могло уже выполниться. Сначала изучите `task.state()` и только затем решайте,
+  нужен ли повтор. Таймаут или отмена async-корутины не доказывают, что сервер
+  остановил исполнение.
+- Для удалённого сервера требуется HTTPS. HTTP доступен для локальной разработки;
+  перенаправления HTTP не выполняются, чтобы не передавать токен другому адресу.
+
+## Разработка
+
+```sh
+uv sync --python 3.12
+uv run pytest
+uv run ruff check .
+uv run mypy src
+uv build
+```
+
+Пакет не импортирует backend платформы. Sync/async тестируются через HTTPX
+MockTransport против одного контракта `/api/agent-env`.
+Публикация описана в [PUBLISHING.md](https://github.com/ai-security-lab-itmo/hundredflags-sdk/blob/main/PUBLISHING.md).
+
+## Runtime contract
+
+Version 0.3 targets the coordinated `2026-09-runtime-1` platform release. HTTP failures use `{ "error": { "code", "message", "details" }, "usage", "retry_after" }`. Task prerequisite and completion metadata refer to explicit task IDs; shared environment state does not imply shared task credit. Upgrade the platform, course clients, and SDK together.

hundredflags_sdk-0.4.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+ai_security_school_sdk/__init__.py,sha256=I4v9sUJ6uj6DH9vTe1CMuFZqmmoKeUq9dSKgCm3xwWQ,1494
+ai_security_school_sdk/async_client.py,sha256=S0rPROmQ53bDX7EN7S7j9b9-jZvGJnugxJe-kFeDFvg,701
+ai_security_school_sdk/client.py,sha256=xOUJfI-1xOoDbHFxPDrJKhTPGOOkYhW4chKbHpW9EGE,583
+ai_security_school_sdk/errors.py,sha256=vmyiBLUAkJvgnt4WSa6HYrR9JYhMNBtP3mkhDu7goeA,1029
+ai_security_school_sdk/models.py,sha256=EVocNE-PevYveWyY9eMlEMqxk8lz0os8WKjMU1vETuU,705
+ai_security_school_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hundredflags_sdk/__init__.py,sha256=LbDnXMXXubXQgIlnzkaJ6unSX1taEHE86gnpxFjBWcM,1073
+hundredflags_sdk/_handles.py,sha256=jaN9RjQ6otSoLkDEJ6s2jCR2xF0gTb0hfePmWUV4SCU,843
+hundredflags_sdk/_http.py,sha256=E5R9bgAo85zQli04cz_HOeQKANanr8ciWO7yRfMC_dU,5039
+hundredflags_sdk/_schema.py,sha256=HvHidhn1wD5XTvT8oe-J1B2i5QWzaNNOm04Olrrhy9g,2855
+hundredflags_sdk/async_client.py,sha256=3wkXTheSnyCSCeQrJp-m403jTOyZhxCk3YjKmJlqw2U,8459
+hundredflags_sdk/client.py,sha256=yeY-05hrJ69Zqrzeyg8gIlUWzbyUox5paRYAa7EknFw,8017
+hundredflags_sdk/errors.py,sha256=3mywC8Fkw0b7xfEXgNKw8iFN-MylXHj0KSXEl369hMA,2239
+hundredflags_sdk/models.py,sha256=2uYomyHl_VnvWIsX5_6OLNVN1QBK7Myvpz9xTCRHJ2A,1613
+hundredflags_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hundredflags_sdk-0.4.0.dist-info/WHEEL,sha256=cmC5s21ojypbVslldL7IJq3hjZH-tINy4rziKePFsG0,81
+hundredflags_sdk-0.4.0.dist-info/METADATA,sha256=P70NGbyLKiS81Xmje_AiRv7TLy3rGHboV-UCL9Vr798,13974
+hundredflags_sdk-0.4.0.dist-info/RECORD,,

hundredflags_sdk-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.23
+Root-Is-Purelib: true
+Tag: py3-none-any