Crear un Adaptador

Los adaptadores conectan RaiSE a servicios externos. Implementan contratos Python Protocol y se descubren via entry points.

Contratos Protocol

RaiSE define dos protocolos de adaptador primarios en rai_cli.adapters.protocols:

ProjectManagementAdapter — para rastreadores de issues:

from typing import Protocol, runtime_checkable

@runtime_checkable
class ProjectManagementAdapter(Protocol):
    def create_issue(self, project_key: str, issue: IssueSpec) -> IssueRef: ...
    def get_issue(self, key: str) -> IssueDetail: ...
    def update_issue(self, key: str, fields: dict[str, Any]) -> IssueRef: ...
    def transition_issue(self, key: str, status: str) -> IssueRef: ...
    def search(self, query: str, limit: int = 50) -> list[IssueSummary]: ...
    def health(self) -> AdapterHealth: ...

DocumentationTarget — para plataformas de documentación:

@runtime_checkable
class DocumentationTarget(Protocol):
    def can_publish(self, doc_type: str, metadata: dict[str, Any]) -> bool: ...
    def publish(self, doc_type: str, content: str, metadata: dict[str, Any]) -> PublishResult: ...
    def get_page(self, identifier: str) -> PageContent: ...
    def search(self, query: str, limit: int = 10) -> list[PageSummary]: ...
    def health(self) -> AdapterHealth: ...

Ambos son @runtime_checkable, por lo que RaiSE verifica el cumplimiento con isinstance().

Arquitectura Async-First

Los adaptadores concretos implementan las variantes async (AsyncProjectManagementAdapter, AsyncDocumentationTarget). El CLI consume wrappers síncronos:

from rai_cli.adapters.sync import SyncPMAdapter

class MyTrackerAsync:
    async def create_issue(self, project_key, issue):
        # Tu implementación async
        ...

# Consumo en CLI
adapter = SyncPMAdapter(MyTrackerAsync())

Registro por Entry Points

Registra tu adaptador en pyproject.toml:

[project.entry-points."rai.adapters.pm"]
my-tracker = "my_package.adapter:MyTrackerAdapter"

[project.entry-points."rai.docs.targets"]
my-docs = "my_package.docs:MyDocsTarget"

Los nombres de los grupos de entry points son contratos estables: - rai.adapters.pm — gestión de proyectos - rai.docs.targets — documentación - rai.governance.schemas — esquemas de gobernanza - rai.governance.parsers — parsers de gobernanza - rai.graph.backends — almacenamiento de graph

Validación

Tras el registro, verifica tu adaptador:

# Listar todos los adaptadores descubiertos
rai adapter list

# Verificar cumplimiento del Protocol
rai adapter check

# Validar config YAML declarativa
rai adapter validate .raise/adapters/my-tracker.yaml

rai adapter check carga cada entry point registrado y ejecuta isinstance() contra el contrato Protocol. Los fallos muestran qué métodos faltan.