Asset create/list/get, Metadata add/list, Lifecycle transition, Relationship create/list, Audit event query, Policy evaluation

src/kontextual_engine/api/app.py

@@ -11,8 +11,23 @@ from importlib import metadata
 from typing import Any
 
 from kontextual_engine.adapters.memory import InMemoryAssetRegistryRepository
-from kontextual_engine.core import utc_now
-from kontextual_engine.ports import AssetRegistryRepository
+from kontextual_engine.core import (
+    Actor,
+    ActorType,
+    Classification,
+    ContextEntity,
+    ContextEntityType,
+    LifecycleState,
+    MetadataRecord,
+    OperationContext,
+    PolicyDecision,
+    RelationshipTargetKind,
+    SourceReference,
+    utc_now,
+)
+from kontextual_engine.errors import AuthorizationError, KontextualError, NotFoundError, ValidationError
+from kontextual_engine.ports import AllowAllPolicyGateway, AssetRegistryRepository, PolicyGateway
+from kontextual_engine.services import AssetRegistryService
 
 
 API_VERSION = "v1"
@@ -22,10 +37,33 @@ OPENAPI_VERSION = "1.0.0"
 @dataclass
 class ServiceRuntime:
     repository: AssetRegistryRepository = field(default_factory=InMemoryAssetRegistryRepository)
+    policy_gateway: PolicyGateway = field(default_factory=AllowAllPolicyGateway)
     api_version: str = API_VERSION
     service_name: str = "kontextual-engine"
     started_at: str = field(default_factory=lambda: utc_now().isoformat())
 
+    def asset_service(self) -> AssetRegistryService:
+        return AssetRegistryService(self.repository, policy_gateway=self.policy_gateway)
+
+    def operation_context(
+        self,
+        *,
+        actor_id: str = "api-user",
+        actor_type: str = "human",
+        display_name: str | None = None,
+        correlation_id: str | None = None,
+        groups: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> OperationContext:
+        actor = Actor.create(
+            ActorType(actor_type),
+            actor_id=actor_id,
+            display_name=display_name,
+            groups=groups,
+            metadata=metadata,
+        )
+        return OperationContext.create(actor, correlation_id=correlation_id)
+
     @property
     def package_version(self) -> str:
         try:
@@ -75,10 +113,155 @@ class ServiceRuntime:
             "openapi_version": OPENAPI_VERSION,
         }
 
+    def create_asset(self, payload: dict[str, Any], context: OperationContext) -> dict[str, Any]:
+        classification = Classification.from_dict(payload["classification"])
+        result = self.asset_service().create_asset(
+            payload["title"],
+            classification,
+            context,
+            asset_id=payload.get("asset_id"),
+            source_refs=[_source_reference(item) for item in payload.get("source_refs", ())],
+            metadata_records=[_metadata_record(item) for item in payload.get("metadata_records", ())],
+            idempotency_key=payload.get("idempotency_key"),
+        )
+        return _asset_change_result(result)
+
+    def get_asset(self, asset_id: str) -> dict[str, Any]:
+        return self.asset_service().get_asset(asset_id).to_dict()
+
+    def list_assets(
+        self,
+        *,
+        lifecycle: str | None = None,
+        asset_type: str | None = None,
+        sensitivity: str | None = None,
+        owner: str | None = None,
+        topic: str | None = None,
+        review_state: str | None = None,
+    ) -> dict[str, Any]:
+        assets = self.asset_service().list_assets(
+            lifecycle=LifecycleState(lifecycle) if lifecycle else None,
+            asset_type=asset_type,
+            sensitivity=sensitivity,
+            owner=owner,
+            topic=topic,
+            review_state=review_state,
+        )
+        return {"items": [asset.to_dict() for asset in assets], "count": len(assets)}
+
+    def add_metadata_record(
+        self,
+        asset_id: str,
+        payload: dict[str, Any],
+        context: OperationContext,
+    ) -> dict[str, Any]:
+        result = self.asset_service().add_metadata_record(
+            asset_id,
+            _metadata_record(payload),
+            context,
+            expected_current_version_id=payload.get("expected_current_version_id"),
+        )
+        return _asset_change_result(result)
+
+    def list_metadata_records(self, asset_id: str) -> dict[str, Any]:
+        records = self.repository.list_metadata_records(asset_id)
+        return {"items": [record.to_dict() for record in records], "count": len(records)}
+
+    def transition_lifecycle(
+        self,
+        asset_id: str,
+        payload: dict[str, Any],
+        context: OperationContext,
+    ) -> dict[str, Any]:
+        result = self.asset_service().transition_lifecycle(
+            asset_id,
+            LifecycleState(payload["lifecycle"]),
+            context,
+            expected_current_version_id=payload.get("expected_current_version_id"),
+        )
+        return _asset_change_result(result)
+
+    def create_relationship(self, payload: dict[str, Any], context: OperationContext) -> dict[str, Any]:
+        target_kind = RelationshipTargetKind(payload.get("target_kind", RelationshipTargetKind.ASSET.value))
+        service = self.asset_service()
+        if target_kind == RelationshipTargetKind.CONTEXT_ENTITY:
+            entity_payload = payload.get("context_entity") or {}
+            entity = ContextEntity(
+                entity_id=payload["target_id"],
+                entity_type=ContextEntityType(entity_payload.get("entity_type", ContextEntityType.TOPIC.value)),
+                name=entity_payload.get("name", payload["target_id"]),
+                external_ref=entity_payload.get("external_ref"),
+                metadata=dict(entity_payload.get("metadata", {})),
+            )
+            result = service.link_asset_to_context_entity(
+                payload["source_asset_id"],
+                entity,
+                payload["predicate"],
+                context,
+                confidence=payload.get("confidence"),
+                provenance=dict(payload.get("provenance", {})),
+                expected_current_version_id=payload.get("expected_current_version_id"),
+            )
+        else:
+            result = service.link_asset_to_asset(
+                payload["source_asset_id"],
+                payload["target_id"],
+                payload["predicate"],
+                context,
+                confidence=payload.get("confidence"),
+                provenance=dict(payload.get("provenance", {})),
+                expected_current_version_id=payload.get("expected_current_version_id"),
+            )
+        return {
+            "relationship": result.relationship.to_dict(),
+            "version": result.version.to_dict(),
+            "audit_event": result.audit_event.to_dict(),
+            "policy_decision": result.policy_decision.to_dict(),
+        }
+
+    def list_relationships(
+        self,
+        *,
+        source_id: str | None = None,
+        target_id: str | None = None,
+    ) -> dict[str, Any]:
+        relationships = self.repository.list_relationships(source_id=source_id, target_id=target_id)
+        return {
+            "items": [relationship.to_dict() for relationship in relationships],
+            "count": len(relationships),
+        }
+
+    def list_audit_events(
+        self,
+        *,
+        target: str | None = None,
+        correlation_id: str | None = None,
+    ) -> dict[str, Any]:
+        events = self.repository.list_audit_events(target=target, correlation_id=correlation_id)
+        return {"items": [event.to_dict() for event in events], "count": len(events)}
+
+    def evaluate_policy(self, payload: dict[str, Any], context: OperationContext) -> dict[str, Any]:
+        try:
+            decision = self.policy_gateway.authorize(
+                context,
+                payload["action"],
+                payload["resource"],
+                resource_metadata=dict(payload.get("resource_metadata", {})),
+            )
+        except Exception as exc:
+            decision = PolicyDecision.fail_closed(
+                context.actor.id,
+                payload.get("action", "unknown"),
+                payload.get("resource", "unknown"),
+                reason=str(exc),
+                context={"gateway_error": type(exc).__name__},
+            )
+        return decision.to_dict()
+
 
 def create_app(runtime: ServiceRuntime | None = None):
     try:
-        from fastapi import FastAPI
+        from fastapi import Depends, FastAPI, Header, HTTPException, Query
     except ImportError as exc:  # pragma: no cover - exercised when optional extra is absent
         raise RuntimeError(
             "FastAPI service dependencies are not installed. Install kontextual-engine[service]."
@@ -120,4 +303,151 @@ def create_app(runtime: ServiceRuntime | None = None):
     def versioned_version() -> dict[str, Any]:
         return runtime.version()
 
+    def context_from_headers(
+        x_actor_id: str = Header("api-user"),
+        x_actor_type: str = Header("human"),
+        x_actor_display_name: str | None = Header(None),
+        x_correlation_id: str | None = Header(None),
+    ) -> OperationContext:
+        return runtime.operation_context(
+            actor_id=x_actor_id,
+            actor_type=x_actor_type,
+            display_name=x_actor_display_name,
+            correlation_id=x_correlation_id,
+        )
+
+    def response(callable_obj, *args: Any, **kwargs: Any) -> Any:
+        try:
+            return callable_obj(*args, **kwargs)
+        except NotFoundError as exc:
+            raise HTTPException(status_code=404, detail=_error_payload(exc)) from exc
+        except AuthorizationError as exc:
+            raise HTTPException(status_code=403, detail=_error_payload(exc)) from exc
+        except ValidationError as exc:
+            raise HTTPException(status_code=422, detail=_error_payload(exc)) from exc
+        except KontextualError as exc:
+            raise HTTPException(status_code=400, detail=_error_payload(exc)) from exc
+
+    @app.post(f"{prefix}/assets", tags=["assets"])
+    def create_asset(
+        payload: dict[str, Any],
+        context: OperationContext = Depends(context_from_headers),
+    ) -> dict[str, Any]:
+        return response(runtime.create_asset, payload, context)
+
+    @app.get(f"{prefix}/assets", tags=["assets"])
+    def list_assets(
+        lifecycle: str | None = Query(None),
+        asset_type: str | None = Query(None),
+        sensitivity: str | None = Query(None),
+        owner: str | None = Query(None),
+        topic: str | None = Query(None),
+        review_state: str | None = Query(None),
+    ) -> dict[str, Any]:
+        return response(
+            runtime.list_assets,
+            lifecycle=lifecycle,
+            asset_type=asset_type,
+            sensitivity=sensitivity,
+            owner=owner,
+            topic=topic,
+            review_state=review_state,
+        )
+
+    @app.get(f"{prefix}/assets/{{asset_id}}", tags=["assets"])
+    def get_asset(asset_id: str) -> dict[str, Any]:
+        return response(runtime.get_asset, asset_id)
+
+    @app.post(f"{prefix}/assets/{{asset_id}}/metadata", tags=["metadata"])
+    def add_metadata(
+        asset_id: str,
+        payload: dict[str, Any],
+        context: OperationContext = Depends(context_from_headers),
+    ) -> dict[str, Any]:
+        return response(runtime.add_metadata_record, asset_id, payload, context)
+
+    @app.get(f"{prefix}/assets/{{asset_id}}/metadata", tags=["metadata"])
+    def list_metadata(asset_id: str) -> dict[str, Any]:
+        return response(runtime.list_metadata_records, asset_id)
+
+    @app.post(f"{prefix}/assets/{{asset_id}}/lifecycle", tags=["assets"])
+    def transition_lifecycle(
+        asset_id: str,
+        payload: dict[str, Any],
+        context: OperationContext = Depends(context_from_headers),
+    ) -> dict[str, Any]:
+        return response(runtime.transition_lifecycle, asset_id, payload, context)
+
+    @app.post(f"{prefix}/relationships", tags=["relationships"])
+    def create_relationship(
+        payload: dict[str, Any],
+        context: OperationContext = Depends(context_from_headers),
+    ) -> dict[str, Any]:
+        return response(runtime.create_relationship, payload, context)
+
+    @app.get(f"{prefix}/relationships", tags=["relationships"])
+    def list_relationships(
+        source_id: str | None = Query(None),
+        target_id: str | None = Query(None),
+    ) -> dict[str, Any]:
+        return response(runtime.list_relationships, source_id=source_id, target_id=target_id)
+
+    @app.get(f"{prefix}/audit/events", tags=["audit"])
+    def list_audit_events(
+        target: str | None = Query(None),
+        correlation_id: str | None = Query(None),
+    ) -> dict[str, Any]:
+        return response(runtime.list_audit_events, target=target, correlation_id=correlation_id)
+
+    @app.post(f"{prefix}/policy/evaluate", tags=["policy"])
+    def evaluate_policy(
+        payload: dict[str, Any],
+        context: OperationContext = Depends(context_from_headers),
+    ) -> dict[str, Any]:
+        return response(runtime.evaluate_policy, payload, context)
+
     return app
+
+
+def _metadata_record(data: dict[str, Any]) -> MetadataRecord:
+    if "record_id" in data and "created_at" in data:
+        return MetadataRecord.from_dict(data)
+    return MetadataRecord(
+        key=data["key"],
+        value=data.get("value"),
+        provenance=dict(data.get("provenance", {})),
+        confidence=data.get("confidence"),
+        confirmed=bool(data.get("confirmed", False)),
+        record_id=data.get("record_id") or MetadataRecord(data["key"], data.get("value")).record_id,
+    )
+
+
+def _source_reference(data: dict[str, Any]) -> SourceReference:
+    if "id" in data:
+        return SourceReference.from_dict(data)
+    return SourceReference(
+        source_system=data["source_system"],
+        path=data.get("path"),
+        uri=data.get("uri"),
+        external_id=data.get("external_id"),
+        checksum=data.get("checksum"),
+        connector_ref=data.get("connector_ref"),
+        metadata=dict(data.get("metadata", {})),
+    )
+
+
+def _asset_change_result(result: Any) -> dict[str, Any]:
+    return {
+        "asset": result.asset.to_dict(),
+        "version": result.version.to_dict(),
+        "audit_event": result.audit_event.to_dict(),
+        "policy_decision": result.policy_decision.to_dict(),
+    }
+
+
+def _error_payload(error: KontextualError) -> dict[str, Any]:
+    return {
+        "code": error.code,
+        "message": str(error),
+        "details": dict(error.details),
+    }