atlas-agent-adapters 1.0.1__tar.gz

atlas_agent_adapters-1.0.1/.gitignore

@@ -0,0 +1,35 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+coverage.xml
+reports/release/*coverage.xml
+reports/release/junit.xml
+reports/release/bandit.json
+reports/release/dependency-audit.json
+reports/release/requirements-audit.txt
+.mypy_cache/
+.pytest_cache/
+.tmp-pytest-*/
+.tmp-pytest/
+.ruff_cache/
+.uv-cache/
+.venv/
+build/
+dist/
+/release/
+bin/
+obj/
+htmlcov/
+.env
+.env.*
+!.env.example
+*.key
+*.log
+*.pem
+*.tmp
+*.swp
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/

atlas_agent_adapters-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jorge Medina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

atlas_agent_adapters-1.0.1/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.5
+Name: atlas-agent-adapters
+Version: 1.0.1
+Summary: Adapters externos REST, gRPC e orientados a eventos para o Atlas
+Project-URL: Repository, https://github.com/Medicode/ai-agent-framework
+Project-URL: Documentation, https://github.com/Medicode/ai-agent-framework/tree/main/docs/adapters
+Project-URL: Issues, https://github.com/Medicode/ai-agent-framework/issues
+Author: Jorge Medina
+Maintainer: Jorge Medina
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: atlas-agent-core~=1.0.1
+Requires-Dist: pydantic<3,>=2.13
+Provides-Extra: grpc
+Requires-Dist: grpcio<2,>=1.81.1; extra == 'grpc'
+Requires-Dist: protobuf<7,>=6.33.5; extra == 'grpc'
+Provides-Extra: rest
+Requires-Dist: fastapi<1,>=0.141; extra == 'rest'
+Description-Content-Type: text/markdown
+
+# atlas-agent-adapters
+
+Adapters externos opcionais para REST, gRPC e mensageria.
+
+Este pacote integra o ecossistema modular Atlas Agent Framework. Consulte a
+[documentação oficial](https://github.com/Medicode/ai-agent-framework/tree/main/docs)
+para instalação, compatibilidade e APIs públicas.

atlas_agent_adapters-1.0.1/README.md

@@ -0,0 +1,7 @@
+# atlas-agent-adapters
+
+Adapters externos opcionais para REST, gRPC e mensageria.
+
+Este pacote integra o ecossistema modular Atlas Agent Framework. Consulte a
+[documentação oficial](https://github.com/Medicode/ai-agent-framework/tree/main/docs)
+para instalação, compatibilidade e APIs públicas.

atlas_agent_adapters-1.0.1/proto/atlas_agents/adapters/grpc/v1/agent_execution.proto

@@ -0,0 +1,144 @@
+syntax = "proto3";
+
+package atlas.agent.v1;
+
+import "google/protobuf/struct.proto";
+import "google/protobuf/timestamp.proto";
+
+enum ApprovalDecision {
+  APPROVAL_DECISION_UNSPECIFIED = 0;
+  APPROVAL_DECISION_APPROVE = 1;
+  APPROVAL_DECISION_REJECT = 2;
+}
+
+message Attachment {
+  string attachment_id = 1;
+  string name = 2;
+  string media_type = 3;
+  string uri = 4;
+  google.protobuf.Struct metadata = 5;
+}
+
+message AgentInput {
+  string message = 1;
+  repeated Attachment attachments = 2;
+  google.protobuf.Struct metadata = 3;
+}
+
+message ExecutionContext {
+  optional string session_id = 1;
+  google.protobuf.Struct metadata = 2;
+}
+
+message RequestedLimits {
+  optional int32 max_turns = 1;
+  optional int32 max_tool_calls = 2;
+  optional int64 max_input_tokens = 3;
+  optional int64 max_output_tokens = 4;
+  optional int64 max_total_tokens = 5;
+  optional double timeout_seconds = 6;
+}
+
+message RequestedBudget {
+  optional string max_estimated_cost = 1;
+  optional string currency = 2;
+}
+
+message ExecuteRequest {
+  string request_id = 1;
+  string agent_id = 2;
+  AgentInput input = 3;
+  ExecutionContext context = 4;
+  RequestedLimits requested_limits = 5;
+  RequestedBudget requested_budget = 6;
+  google.protobuf.Struct metadata = 7;
+}
+
+message ResumeRequest {
+  string request_id = 1;
+  string agent_id = 2;
+  string resume_token = 3;
+  string approval_request_id = 4;
+  ApprovalDecision decision = 5;
+  optional string reason = 6;
+  google.protobuf.Timestamp decided_at = 7;
+  google.protobuf.Struct metadata = 8;
+}
+
+message Error {
+  string code = 1;
+  string message = 2;
+  bool retryable = 3;
+  google.protobuf.Struct details = 4;
+}
+
+message Usage {
+  int64 input_tokens = 1;
+  int64 output_tokens = 2;
+  int64 cached_input_tokens = 3;
+  int64 reasoning_tokens = 4;
+  optional string estimated_cost = 5;
+}
+
+message Citation {
+  string citation_key = 1;
+  string source_id = 2;
+  string document_id = 3;
+  string passage_id = 4;
+  optional string title = 5;
+  optional string uri = 6;
+  optional int32 page = 7;
+  optional string section = 8;
+}
+
+message ApprovalSubject {
+  string tool_call_id = 1;
+  string tool_name = 2;
+  repeated string argument_keys = 3;
+}
+
+message ApprovalRequest {
+  string approval_request_id = 1;
+  string execution_id = 2;
+  string agent_id = 3;
+  string kind = 4;
+  string summary = 5;
+  string reason = 6;
+  google.protobuf.Timestamp requested_at = 7;
+  optional google.protobuf.Timestamp expires_at = 8;
+  ApprovalSubject subject = 9;
+}
+
+message Suspension {
+  string execution_id = 1;
+  ApprovalRequest approval_request = 2;
+  string resume_token = 3;
+  int32 checkpoint_version = 4;
+  google.protobuf.Timestamp created_at = 5;
+}
+
+message ExecuteResponse {
+  string request_id = 1;
+  string execution_id = 2;
+  string status = 3;
+  google.protobuf.Value output = 4;
+  optional Error error = 5;
+  optional Usage usage = 6;
+  repeated Citation citations = 7;
+  optional Suspension suspension = 8;
+  google.protobuf.Struct metadata = 9;
+}
+
+message StreamItem {
+  string type = 1;
+  int64 sequence = 2;
+  string execution_id = 3;
+  google.protobuf.Struct data = 4;
+}
+
+service AgentExecutionService {
+  rpc Execute(ExecuteRequest) returns (ExecuteResponse);
+  rpc Stream(ExecuteRequest) returns (stream StreamItem);
+  rpc Resume(ResumeRequest) returns (ExecuteResponse);
+  rpc ResumeStream(ResumeRequest) returns (stream StreamItem);
+}

atlas_agent_adapters-1.0.1/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "atlas-agent-adapters"
+dynamic = ["version"]
+description = "Adapters externos REST, gRPC e orientados a eventos para o Atlas"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+authors = [{ name = "Jorge Medina" }]
+maintainers = [{ name = "Jorge Medina" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "atlas-agent-core~=1.0.1",
+    "pydantic>=2.13,<3",
+]
+
+[project.optional-dependencies]
+rest = ["fastapi>=0.141,<1"]
+grpc = ["grpcio>=1.81.1,<2", "protobuf>=6.33.5,<7"]
+
+[project.urls]
+Repository = "https://github.com/Medicode/ai-agent-framework"
+Documentation = "https://github.com/Medicode/ai-agent-framework/tree/main/docs/adapters"
+Issues = "https://github.com/Medicode/ai-agent-framework/issues"
+
+[tool.hatch.version]
+path = "src/atlas_agents/adapters/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/atlas_agents"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"proto/atlas_agents/adapters/grpc/v1/agent_execution.proto" = "atlas_agents/adapters/grpc/v1/agent_execution.proto"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/atlas_agents/adapters", "proto", "LICENSE", "README.md", "pyproject.toml"]

atlas_agent_adapters-1.0.1/src/atlas_agents/adapters/__init__.py

@@ -0,0 +1,107 @@
+"""External transport adapters over one application execution facade."""
+
+from atlas_agents.adapters._version import __version__
+from atlas_agents.adapters.errors import (
+    AdapterConfigurationError,
+    AdapterError,
+    AdapterSerializationError,
+    AdapterStreamingError,
+    AdapterUnavailableError,
+    AgentAccessDeniedError,
+    AgentNotRegisteredError,
+    DuplicateAgentError,
+    IdempotencyConflictError,
+    IdentityMappingError,
+    InvalidExternalRequestError,
+)
+from atlas_agents.adapters.idempotency import (
+    IdempotencyRecord,
+    IdempotencyState,
+    IdempotencyStore,
+    InMemoryIdempotencyStore,
+)
+from atlas_agents.adapters.models import (
+    AdapterErrorResponse,
+    AdapterExecutionStatus,
+    ApprovalRequestDTO,
+    CitationDTO,
+    ExecuteAgentRequest,
+    ExecuteAgentResponse,
+    ExecutionStreamItem,
+    ExecutionSuspensionDTO,
+    ExternalAgentInput,
+    ExternalAttachment,
+    ExternalExecutionContext,
+    ReadinessResponse,
+    RequestedExecutionBudget,
+    RequestedExecutionLimits,
+    ResumeExecutionRequest,
+    TransportPrincipal,
+    UsageDTO,
+)
+from atlas_agents.adapters.optional import MissingAdapterDependencyError
+from atlas_agents.adapters.policies import (
+    AgentAccessPolicy,
+    AgentOperation,
+    AllowAllAgentAccessPolicy,
+    BoundedExecutionPolicyResolver,
+    EffectiveExecutionPolicy,
+    ExecutionIdentityMapper,
+    ExecutionPolicyResolver,
+    SubjectExecutionIdentityMapper,
+)
+from atlas_agents.adapters.registry import AgentRegistry
+from atlas_agents.adapters.service import (
+    AgentExecutionService,
+    AgentRegistryPort,
+    AgentRuntimePort,
+)
+
+__all__ = [
+    "AdapterConfigurationError",
+    "AdapterError",
+    "AdapterErrorResponse",
+    "AdapterExecutionStatus",
+    "AdapterSerializationError",
+    "AdapterStreamingError",
+    "AdapterUnavailableError",
+    "AgentAccessDeniedError",
+    "AgentAccessPolicy",
+    "AgentExecutionService",
+    "AgentNotRegisteredError",
+    "AgentOperation",
+    "AgentRegistry",
+    "AgentRegistryPort",
+    "AgentRuntimePort",
+    "AllowAllAgentAccessPolicy",
+    "ApprovalRequestDTO",
+    "BoundedExecutionPolicyResolver",
+    "CitationDTO",
+    "DuplicateAgentError",
+    "EffectiveExecutionPolicy",
+    "ExecuteAgentRequest",
+    "ExecuteAgentResponse",
+    "ExecutionIdentityMapper",
+    "ExecutionPolicyResolver",
+    "ExecutionStreamItem",
+    "ExecutionSuspensionDTO",
+    "ExternalAgentInput",
+    "ExternalAttachment",
+    "ExternalExecutionContext",
+    "IdempotencyConflictError",
+    "IdempotencyRecord",
+    "IdempotencyState",
+    "IdempotencyStore",
+    "IdentityMappingError",
+    "InMemoryIdempotencyStore",
+    "InvalidExternalRequestError",
+    "MissingAdapterDependencyError",
+    "ReadinessResponse",
+    "RequestedExecutionBudget",
+    "RequestedExecutionLimits",
+    "ResumeExecutionRequest",
+    "SubjectExecutionIdentityMapper",
+    "TransportPrincipal",
+    "UsageDTO",
+    "__version__",
+]

atlas_agent_adapters-1.0.1/src/atlas_agents/adapters/_version.py

@@ -0,0 +1,3 @@
+"""Package version generated from the repository VERSION file."""
+
+__version__ = "1.0.1"

atlas_agent_adapters-1.0.1/src/atlas_agents/adapters/errors.py

@@ -0,0 +1,71 @@
+"""Safe application and transport adapter errors."""
+
+from atlas_agents.exceptions import AtlasAgentError
+
+
+class AdapterError(AtlasAgentError):
+    """Base error with a stable wire code and retry indication."""
+
+    code = "adapter_error"
+    retryable = False
+
+
+class AdapterConfigurationError(AdapterError):
+    """Report invalid explicit adapter configuration."""
+
+    code = "adapter_configuration_error"
+
+
+class AgentNotRegisteredError(AdapterError):
+    """Report an unknown agent without exposing registry contents."""
+
+    code = "agent_not_registered"
+
+
+class DuplicateAgentError(AdapterError):
+    """Reject silent replacement of an existing agent."""
+
+    code = "duplicate_agent"
+
+
+class AgentAccessDeniedError(AdapterError):
+    """Report transport-level agent authorization denial."""
+
+    code = "agent_access_denied"
+
+
+class InvalidExternalRequestError(AdapterError):
+    """Report semantically invalid external input."""
+
+    code = "invalid_external_request"
+
+
+class IdentityMappingError(AdapterError):
+    """Report failure to map a trusted transport principal."""
+
+    code = "identity_mapping_error"
+
+
+class IdempotencyConflictError(AdapterError):
+    """Report reuse of a key with a different canonical request."""
+
+    code = "idempotency_conflict"
+
+
+class AdapterSerializationError(AdapterError):
+    """Report data that cannot cross a wire boundary."""
+
+    code = "adapter_serialization_error"
+
+
+class AdapterStreamingError(AdapterError):
+    """Report an adapter streaming failure."""
+
+    code = "adapter_streaming_error"
+
+
+class AdapterUnavailableError(AdapterError):
+    """Report a transient application or transport dependency failure."""
+
+    code = "adapter_unavailable"
+    retryable = True

atlas_agent_adapters-1.0.1/src/atlas_agents/adapters/events/__init__.py

@@ -0,0 +1,29 @@
+"""Provider-neutral event-driven adapter contracts and consumer."""
+
+from atlas_agents.adapters.events.consumer import ExecutionCommandConsumer
+from atlas_agents.adapters.events.models import (
+    EventAdapterConfig,
+    EventPublicationMode,
+    ExecuteAgentCommand,
+    MessageEnvelope,
+    MessagePrincipalResolver,
+    MessageProcessingResult,
+    ResumeExecutionCommand,
+    TrustedContextPrincipalResolver,
+    TrustedMessageContext,
+)
+from atlas_agents.adapters.events.publisher import ExecutionEventPublisher
+
+__all__ = [
+    "EventAdapterConfig",
+    "EventPublicationMode",
+    "ExecuteAgentCommand",
+    "ExecutionCommandConsumer",
+    "ExecutionEventPublisher",
+    "MessageEnvelope",
+    "MessagePrincipalResolver",
+    "MessageProcessingResult",
+    "ResumeExecutionCommand",
+    "TrustedContextPrincipalResolver",
+    "TrustedMessageContext",
+]

atlas_agent_adapters-1.0.1/src/atlas_agents/adapters/events/consumer.py

@@ -0,0 +1,168 @@
+"""Broker-neutral command handler over the shared execution service."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import UTC, datetime
+from typing import cast
+from uuid import uuid4
+
+from pydantic import JsonValue, ValidationError
+
+from atlas_agents.adapters.errors import AdapterError, AdapterUnavailableError
+from atlas_agents.adapters.events.models import (
+    EventAdapterConfig,
+    EventPublicationMode,
+    ExecuteAgentCommand,
+    MessageEnvelope,
+    MessagePrincipalResolver,
+    MessageProcessingResult,
+    ResumeExecutionCommand,
+    TrustedMessageContext,
+)
+from atlas_agents.adapters.events.publisher import ExecutionEventPublisher
+from atlas_agents.adapters.models import (
+    ExecuteAgentRequest,
+    ExecuteAgentResponse,
+    ResumeExecutionRequest,
+    TransportPrincipal,
+)
+from atlas_agents.adapters.service import AgentExecutionService
+
+
+class ExecutionCommandConsumer:
+    """Handle execute and resume commands without owning broker lifecycle."""
+
+    def __init__(
+        self,
+        *,
+        service: AgentExecutionService,
+        publisher: ExecutionEventPublisher,
+        principal_resolver: MessagePrincipalResolver,
+        config: EventAdapterConfig | None = None,
+        message_id_factory: Callable[[], str] | None = None,
+    ) -> None:
+        """Store explicit dependencies and safe event configuration."""
+        self._service = service
+        self._publisher = publisher
+        self._principal_resolver = principal_resolver
+        self._config = config or EventAdapterConfig()
+        self._message_id_factory = message_id_factory or (lambda: str(uuid4()))
+
+    async def handle(
+        self, envelope: MessageEnvelope, context: TrustedMessageContext
+    ) -> MessageProcessingResult:
+        """Process one delivery and report ack/retry semantics explicitly."""
+        if envelope.schema_version != self._config.schema_version:
+            return MessageProcessingResult(
+                acknowledge=False,
+                retryable=False,
+                error_code="unsupported_schema_version",
+            )
+        try:
+            principal = self._principal_resolver.resolve(envelope, context)
+            if envelope.message_type == "execution.execute":
+                execute_command = ExecuteAgentCommand.model_validate(envelope.payload)
+                await self._execute(envelope, execute_command, principal)
+            elif envelope.message_type == "execution.resume":
+                resume_command = ResumeExecutionCommand.model_validate(envelope.payload)
+                await self._resume(envelope, resume_command, principal)
+            else:
+                return MessageProcessingResult(
+                    acknowledge=False,
+                    retryable=False,
+                    error_code="unsupported_message_type",
+                )
+        except ValidationError:
+            return MessageProcessingResult(
+                acknowledge=False,
+                retryable=False,
+                error_code="invalid_external_request",
+            )
+        except AdapterError as error:
+            return MessageProcessingResult(
+                acknowledge=False,
+                retryable=error.retryable,
+                error_code=error.code,
+            )
+        except Exception:
+            return MessageProcessingResult(
+                acknowledge=False,
+                retryable=True,
+                error_code="adapter_unavailable",
+            )
+        return MessageProcessingResult(acknowledge=True)
+
+    async def _execute(
+        self,
+        envelope: MessageEnvelope,
+        command: ExecuteAgentCommand,
+        principal: TransportPrincipal,
+    ) -> None:
+        request = ExecuteAgentRequest(
+            **command.model_dump(),
+            principal=principal,
+            idempotency_key=envelope.message_id,
+        )
+        if self._config.publication_mode is EventPublicationMode.TERMINAL_ONLY:
+            await self._publish_terminal(envelope, await self._service.execute(request))
+            return
+        async for item in self._service.stream(request):
+            await self._publish(
+                source=envelope,
+                message_type="execution.stream",
+                payload=cast("dict[str, JsonValue]", item.model_dump(mode="json")),
+            )
+
+    async def _resume(
+        self,
+        envelope: MessageEnvelope,
+        command: ResumeExecutionCommand,
+        principal: TransportPrincipal,
+    ) -> None:
+        request = ResumeExecutionRequest(
+            **command.model_dump(),
+            principal=principal,
+            idempotency_key=envelope.message_id,
+        )
+        if self._config.publication_mode is EventPublicationMode.TERMINAL_ONLY:
+            await self._publish_terminal(envelope, await self._service.resume(request))
+            return
+        async for item in self._service.resume_stream(request):
+            await self._publish(
+                source=envelope,
+                message_type="execution.stream",
+                payload=cast("dict[str, JsonValue]", item.model_dump(mode="json")),
+            )
+
+    async def _publish_terminal(
+        self, source: MessageEnvelope, response: ExecuteAgentResponse
+    ) -> None:
+        await self._publish(
+            source=source,
+            message_type=f"execution.{response.status.value}",
+            payload=cast("dict[str, JsonValue]", response.model_dump(mode="json")),
+        )
+
+    async def _publish(
+        self,
+        *,
+        source: MessageEnvelope,
+        message_type: str,
+        payload: dict[str, JsonValue],
+    ) -> None:
+        event = MessageEnvelope(
+            message_id=self._message_id_factory(),
+            message_type=message_type,
+            schema_version=self._config.schema_version,
+            correlation_id=source.correlation_id,
+            causation_id=source.message_id,
+            timestamp=datetime.now(UTC),
+            payload=payload,
+        )
+        try:
+            await self._publisher.publish(event)
+        except Exception:
+            raise AdapterUnavailableError(
+                "Não foi possível publicar o evento de execução."
+            ) from None