forkflux-api 0.1.0__py3-none-any.whl

forkflux_api/config.py

@@ -0,0 +1,67 @@
+import os
+import platform
+from functools import lru_cache
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from pydantic import Field, PostgresDsn, field_validator
+from pydantic_core import MultiHostUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def _default_data_dir(app_name: str) -> Path:
+    system = platform.system().lower()
+
+    if system == "darwin":
+        return Path.home() / "Library" / "Application Support" / app_name
+
+    if system == "windows":
+        appdata = os.environ.get("APPDATA")
+        if appdata:
+            return Path(appdata) / app_name
+        return Path.home() / "AppData" / "Roaming" / app_name
+
+    xdg_data_home = os.environ.get("XDG_DATA_HOME")
+    if xdg_data_home:
+        return Path(xdg_data_home) / app_name
+
+    return Path.home() / ".local" / "share" / app_name
+
+
+def _default_sqlite_db_path() -> Path:
+    return _default_data_dir("forkflux") / "forkflux.db"
+
+
+def _build_default_database_url() -> str:
+    sqlite_path = _default_sqlite_db_path()
+    sqlite_path.parent.mkdir(parents=True, exist_ok=True)
+    return f"sqlite+aiosqlite:///{sqlite_path}"
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env", env_file_encoding="utf-8", extra="ignore", env_nested_max_split=1, env_nested_delimiter="_"
+    )
+
+    database_url: str = Field(default_factory=_build_default_database_url)
+
+    @field_validator("database_url", mode="before")
+    @classmethod
+    def validate_database_url(cls, value: str | MultiHostUrl) -> str:
+        if isinstance(value, MultiHostUrl):
+            return value.__str__()
+
+        scheme = urlsplit(value).scheme
+        if scheme == "sqlite+aiosqlite":
+            return value
+
+        if scheme.startswith("postgresql"):
+            PostgresDsn(value)
+            return value
+
+        raise ValueError("Unsupported database URL scheme. Use sqlite+aiosqlite or postgresql(+driver).")
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    return Settings()

forkflux_api/database.py

@@ -0,0 +1,70 @@
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+from typing import AsyncGenerator
+
+from sqlalchemy import DateTime
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_engine_from_config, async_sessionmaker
+from sqlalchemy.orm import DeclarativeBase, declared_attr
+from sqlalchemy.types import TypeDecorator
+
+from forkflux_api.config import get_settings
+
+
+def get_async_engine(**overrides: str) -> AsyncEngine:
+    settings = get_settings()
+    config: dict[str, str] = {
+        "sqlalchemy.url": settings.database_url,
+        "sqlalchemy.echo": overrides.get("sqlalchemy.echo", "false"),
+    }
+
+    config.update(overrides)
+
+    return async_engine_from_config(config, prefix="sqlalchemy.", pool_pre_ping=True)
+
+
+@asynccontextmanager
+async def session_manager() -> AsyncGenerator[AsyncSession, None]:
+    session_factory = async_sessionmaker(bind=get_async_engine(), expire_on_commit=False)
+    async with session_factory() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+
+
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    async with session_manager() as session:
+        yield session
+
+
+class Base(DeclarativeBase):
+    @declared_attr.directive
+    def __tablename__(cls) -> str:  # pragma: no cover - simple convention helper
+        return cls.__name__.lower()
+
+    __abstract__ = True
+
+
+class UTCDateTime(TypeDecorator[datetime]):
+    impl = DateTime(timezone=True)
+    cache_ok = True
+
+    def process_bind_param(self, value: datetime | None, dialect) -> datetime | None:
+        if value is None:
+            return None
+
+        if value.tzinfo is None:
+            return value.replace(tzinfo=timezone.utc)
+
+        return value.astimezone(timezone.utc)
+
+    def process_result_value(self, value: datetime | None, dialect) -> datetime | None:
+        if value is None:
+            return None
+
+        if value.tzinfo is None:
+            return value.replace(tzinfo=timezone.utc)
+
+        return value.astimezone(timezone.utc)

forkflux_api/dependencies.py

@@ -0,0 +1,87 @@
+import hashlib
+import hmac
+
+from fastapi import Depends, HTTPException, Request, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from forkflux_api.agents.exceptions import AgentApiTokenNotFoundError, AgentIdentityNotFoundError
+from forkflux_api.agents.models import AgentIdentity
+from forkflux_api.agents.respositories import AgentApiTokenRepository, AgentIdentityRepository
+from forkflux_api.agents.services import AgentApiTokenService, AgentIdentityService
+from forkflux_api.database import get_session
+
+bearer_scheme = HTTPBearer(auto_error=False)
+
+
+def get_trace_id(request: Request) -> str:
+    return request.state.trace_id
+
+
+def get_agent_api_token_repo(
+    session: AsyncSession = Depends(get_session), trace_id: str = Depends(get_trace_id)
+) -> AgentApiTokenRepository:
+    return AgentApiTokenRepository(session=session, trace_id=trace_id)
+
+
+def get_agent_api_token_service(
+    repository: AgentApiTokenRepository = Depends(get_agent_api_token_repo), trace_id: str = Depends(get_trace_id)
+) -> AgentApiTokenService:
+    return AgentApiTokenService(agent_api_token_repo=repository, trace_id=trace_id)
+
+
+def get_agent_identity_repo(
+    session: AsyncSession = Depends(get_session), trace_id: str = Depends(get_trace_id)
+) -> AgentIdentityRepository:
+    return AgentIdentityRepository(session=session, trace_id=trace_id)
+
+
+def get_agent_identity_service(
+    repository: AgentIdentityRepository = Depends(get_agent_identity_repo), trace_id: str = Depends(get_trace_id)
+) -> AgentIdentityService:
+    return AgentIdentityService(agent_identity_repo=repository, trace_id=trace_id)
+
+
+async def verify_token(
+    credentials: HTTPAuthorizationCredentials | None = Depends(bearer_scheme),
+    service: AgentApiTokenService = Depends(get_agent_api_token_service),
+) -> dict[str, int]:
+    if credentials is None:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Not authenticated",
+        )
+
+    token = credentials.credentials
+    provided_hash = hashlib.sha256(token.encode()).hexdigest()
+
+    try:
+        entity = await service.get_token(token_hash=provided_hash)
+
+        if not hmac.compare_digest(provided_hash, entity.token_hash):
+            raise AgentApiTokenNotFoundError
+
+        return {"agent_id": entity.agent_id}
+    except AgentApiTokenNotFoundError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or expired token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+
+async def get_current_agent(
+    payload: dict[str, int] = Depends(verify_token),
+    agent_service: AgentIdentityService = Depends(get_agent_identity_service),
+) -> AgentIdentity:
+    agent_id = payload["agent_id"]
+
+    try:
+        agent = await agent_service.get_by_id(agent_id)
+    except AgentIdentityNotFoundError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Agent not found",
+        )
+
+    return agent

forkflux_api/exceptions.py

@@ -0,0 +1,11 @@
+from typing import Any, Literal
+
+
+class BaseValidationError(Exception):
+    code: str
+    msg: str
+
+    def __init__(self, field_name: str, value: Any = None, loc: Literal["body", "query", "header", "path"] = "body"):
+        self.field_name = field_name
+        self.value = value
+        self.loc = loc

forkflux_api/jobs/api_exceptions.py

@@ -0,0 +1,26 @@
+from forkflux_api.exceptions import BaseValidationError
+
+
+class ParentJobValidationError(BaseValidationError):
+    code = "parent_job.invalid"
+    msg = "Parent job is invalid."
+
+
+class TargetRoleValidationError(BaseValidationError):
+    code = "target_role.invalid"
+    msg = "Target role is invalid."
+
+
+class HandoffJobClaimValidationError(BaseValidationError):
+    code = "handoff_job_claim.invalid"
+    msg = "Handoff job claim is invalid."
+
+
+class HandoffJobIdentityValidationError(BaseValidationError):
+    code = "handoff_job_identity.invalid"
+    msg = "Handoff job identity is invalid."
+
+
+class HandoffJobStatusValidationError(BaseValidationError):
+    code = "handoff_job_status.invalid"
+    msg = "Handoff job status transition is invalid."

forkflux_api/jobs/constants.py

@@ -0,0 +1,28 @@
+from enum import Enum, IntEnum
+
+
+class JobStatusEnum(str, Enum):
+    PUBLISHED = "published"
+    CLAIMED = "claimed"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class JobPriorityEnum(IntEnum):
+    LOW = 10
+    NORMAL = 20
+    HIGH = 30
+    URGENT = 40
+
+
+class JobListOrderEnum(str, Enum):
+    CREATED_AT_ASC = "created_at_asc"
+    CREATED_AT_DESC = "created_at_desc"
+    PRIORITY_ASC = "priority_asc"
+    PRIORITY_DESC = "priority_desc"
+
+
+class JobEventTypeEnum(str, Enum):
+    TASK_PUBLISHED = "task_published"

forkflux_api/jobs/dependencies.py

@@ -0,0 +1,85 @@
+from fastapi import Depends, Request
+from forkflux_api.agents.dependencies import get_target_role_service
+from forkflux_api.agents.exceptions import TargetRoleNotFoundError
+from forkflux_api.agents.models import TargetRole
+from forkflux_api.agents.services import TargetRoleService
+from forkflux_api.database import get_session
+from forkflux_api.jobs.api_exceptions import ParentJobValidationError, TargetRoleValidationError
+from forkflux_api.jobs.dto import HandoffJobItem
+from forkflux_api.jobs.exceptions import HandoffJobNotFoundError
+from forkflux_api.jobs.repositories import HandoffJobRepository, JobArtifactRepository, JobEventRepository
+from forkflux_api.jobs.schemas import HandoffJobCreateRequest
+from forkflux_api.jobs.services import HandoffJobService
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+def get_trace_id(request: Request) -> str:
+    return request.state.trace_id
+
+
+async def get_handoff_job_repo(
+    session: AsyncSession = Depends(get_session), trace_id: str = Depends(get_trace_id)
+) -> HandoffJobRepository:
+    return HandoffJobRepository(session=session, trace_id=trace_id)
+
+
+async def get_job_artifact_repo(
+    session: AsyncSession = Depends(get_session), trace_id: str = Depends(get_trace_id)
+) -> JobArtifactRepository:
+    return JobArtifactRepository(session=session, trace_id=trace_id)
+
+
+async def get_job_event_repo(
+    session: AsyncSession = Depends(get_session), trace_id: str = Depends(get_trace_id)
+) -> JobEventRepository:
+    return JobEventRepository(session=session, trace_id=trace_id)
+
+
+def get_handoff_job_service(
+    repository: HandoffJobRepository = Depends(get_handoff_job_repo),
+    job_artifact_repo: JobArtifactRepository = Depends(get_job_artifact_repo),
+    job_event_repo: JobEventRepository = Depends(get_job_event_repo),
+    trace_id: str = Depends(get_trace_id),
+) -> HandoffJobService:
+    return HandoffJobService(
+        handoff_job_repo=repository,
+        job_artifact_repo=job_artifact_repo,
+        job_event_repo=job_event_repo,
+        trace_id=trace_id,
+    )
+
+
+async def validate_parent_job(
+    job_data: HandoffJobCreateRequest, service: HandoffJobService = Depends(get_handoff_job_service)
+) -> HandoffJobItem | None:
+    if job_data.parent_job_id is None:
+        return None
+
+    try:
+        parent_job = await service.get_job(job_id=job_data.parent_job_id)
+        return parent_job
+    except HandoffJobNotFoundError:
+        raise ParentJobValidationError(field_name="parent_job_id", value=job_data.parent_job_id)
+
+
+async def validate_target_role(
+    job_data: HandoffJobCreateRequest, service: TargetRoleService = Depends(get_target_role_service)
+) -> TargetRole:
+    try:
+        target_role = await service.get_by_role_key(role_key=job_data.target_role_key)
+        return target_role
+    except TargetRoleNotFoundError:
+        raise TargetRoleValidationError(field_name="target_role_key", value=job_data.target_role_key)
+
+
+async def validate_target_role_query_param(
+    target_role_key: str | None = None, service: TargetRoleService = Depends(get_target_role_service)
+) -> TargetRole | None:
+    if target_role_key is None or target_role_key.strip() == "":
+        return None
+
+    try:
+        role = await service.get_by_role_key(role_key=target_role_key)
+        return role
+    except TargetRoleNotFoundError:
+        raise TargetRoleValidationError(field_name="target_role_key", value=target_role_key, loc="query")

forkflux_api/jobs/dto.py

@@ -0,0 +1,56 @@
+from dataclasses import dataclass
+from typing import Any, TypedDict
+
+from forkflux_api.jobs.constants import JobListOrderEnum, JobPriorityEnum, JobStatusEnum
+from forkflux_api.jobs.models import HandoffJob, JobArtifact
+
+
+@dataclass(slots=True)
+class HandoffJobCreate:
+    parent_job_id: int | None
+    summary: str
+    context_payload: dict[str, Any]
+    priority: JobPriorityEnum
+    source_agent_id: int
+    target_role_id: int
+    constraints: list[str]
+
+
+@dataclass(slots=True)
+class JobArtifactCreate:
+    job_id: int
+    artifact_type: str
+    artifact_uri: str
+    artifact_checksum: str | None
+    metadata_json: dict[str, Any]
+
+
+@dataclass(slots=True)
+class JobEventCreate:
+    job_id: int
+    event_type: str
+    previous_status: JobStatusEnum | None
+    current_status: JobStatusEnum
+    actor_agent_id: int | None
+    payload_json: dict[str, Any]
+
+
+@dataclass(slots=True)
+class HandoffJobItem:
+    job_details: HandoffJob
+    target_role_key: str
+    source_agent_label: str
+    assignee_agent_label: str | None
+
+
+class HandoffJobWithArtifacts(TypedDict):
+    job: HandoffJobItem
+    artifacts: list[JobArtifact]
+
+
+@dataclass(slots=True)
+class HandoffJobFilterParams:
+    limit: int
+    status: JobStatusEnum | None
+    target_role_id: int | None
+    order: list[JobListOrderEnum]

forkflux_api/jobs/exceptions.py

@@ -0,0 +1,18 @@
+class HandoffJobConflictError(Exception):
+    code = "handoff_job.conflict"
+    msg = "Handoff job conflicts with existing data constraints."
+
+
+class HandoffJobNotFoundError(Exception):
+    code = "handoff_job.not_found"
+    msg = "Handoff job not found."
+
+
+class JobArtifactConflictError(Exception):
+    code = "job_artifact.conflict"
+    msg = "Job artifact conflicts with existing data constraints."
+
+
+class JobEventConflictError(Exception):
+    code = "job_event.conflict"
+    msg = "Job event conflicts with existing data constraints."

forkflux_api/jobs/handlers.py

@@ -0,0 +1,117 @@
+from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi import status as http_status
+from forkflux_api.agents.models import AgentIdentity, TargetRole
+from forkflux_api.dependencies import get_current_agent, verify_token
+from forkflux_api.jobs.api_exceptions import (
+    HandoffJobClaimValidationError,
+    HandoffJobIdentityValidationError,
+    HandoffJobStatusValidationError,
+)
+from forkflux_api.jobs.constants import JobListOrderEnum, JobPriorityEnum, JobStatusEnum
+from forkflux_api.jobs.dependencies import (
+    get_handoff_job_service,
+    validate_parent_job,
+    validate_target_role,
+    validate_target_role_query_param,
+)
+from forkflux_api.jobs.dto import HandoffJobFilterParams
+from forkflux_api.jobs.exceptions import HandoffJobConflictError, HandoffJobNotFoundError
+from forkflux_api.jobs.helpers import handoff_job_to_response_model
+from forkflux_api.jobs.schemas import (
+    HandoffJobChangeStatusRequest,
+    HandoffJobCreateRequest,
+    HandoffJobCreateResponse,
+    HandoffJobListItem,
+    HandoffJobWithArtifactsItem,
+)
+from forkflux_api.jobs.services import HandoffJobService
+
+router = APIRouter(prefix="/jobs", tags=["jobs"], dependencies=[Depends(verify_token)])
+
+
+@router.post(
+    "",
+    response_model=HandoffJobCreateResponse,
+    status_code=http_status.HTTP_201_CREATED,
+    dependencies=[Depends(validate_parent_job)],
+)
+async def create_job(
+    job_data: HandoffJobCreateRequest,
+    valid_target_role: TargetRole = Depends(validate_target_role),
+    current_agent: AgentIdentity = Depends(get_current_agent),
+    job_service: HandoffJobService = Depends(get_handoff_job_service),
+):
+    job_id = await job_service.create_job(job_data, valid_target_role.id, current_agent.id)
+    return {"job_id": job_id}
+
+
+@router.get("", response_model=list[HandoffJobListItem])
+async def list_jobs(
+    limit: int = Query(50, ge=1, le=200),
+    status: JobStatusEnum | None = None,
+    order: list[JobListOrderEnum] = Query(default=[JobListOrderEnum.CREATED_AT_ASC]),
+    target_role_key: TargetRole = Depends(validate_target_role_query_param),
+    my_role_only: bool = True,
+    job_service: HandoffJobService = Depends(get_handoff_job_service),
+    current_agent: AgentIdentity = Depends(get_current_agent),
+):
+    target_role_id = current_agent.role_id if my_role_only else target_role_key.id if target_role_key else None
+    jobs = await job_service.list_jobs(
+        HandoffJobFilterParams(limit=limit, status=status, target_role_id=target_role_id, order=order)
+    )
+    return [
+        HandoffJobListItem(
+            id=x.job_details.id,
+            summary=x.job_details.summary,
+            status=x.job_details.status,
+            priority=JobPriorityEnum(x.job_details.priority),
+            source_agent_label=x.source_agent_label,
+            assignee_agent_label=x.assignee_agent_label,
+            target_role_key=x.target_role_key,
+            created_at=x.job_details.created_at,
+        )
+        for x in jobs
+    ]
+
+
+@router.get("/{job_id}", response_model=HandoffJobWithArtifactsItem)
+async def get_job(
+    job_id: int,
+    job_service: HandoffJobService = Depends(get_handoff_job_service),
+):
+    try:
+        entity = await job_service.get_job_with_artifacts(job_id)
+    except HandoffJobNotFoundError:
+        raise HTTPException(status_code=http_status.HTTP_404_NOT_FOUND, detail=HandoffJobNotFoundError.msg)
+
+    return handoff_job_to_response_model(entity=entity)
+
+
+@router.post("/{job_id}/claim", status_code=http_status.HTTP_201_CREATED, response_model=HandoffJobWithArtifactsItem)
+async def claim_job(
+    job_id: int,
+    job_service: HandoffJobService = Depends(get_handoff_job_service),
+    current_agent: AgentIdentity = Depends(get_current_agent),
+):
+    try:
+        await job_service.claim_job(job_id, current_agent)
+    except HandoffJobNotFoundError, HandoffJobConflictError:
+        raise HandoffJobClaimValidationError(field_name="job_id", value=job_id, loc="path")
+
+    entity = await job_service.get_job_with_artifacts(job_id)
+    return handoff_job_to_response_model(entity=entity)
+
+
+@router.post("/{job_id}/status", status_code=http_status.HTTP_204_NO_CONTENT)
+async def change_job_status(
+    job_id: int,
+    data: HandoffJobChangeStatusRequest,
+    job_service: HandoffJobService = Depends(get_handoff_job_service),
+    current_agent: AgentIdentity = Depends(get_current_agent),
+):
+    try:
+        await job_service.change_job_status(job_id, data.status, current_agent, data.failure_reason)
+    except HandoffJobNotFoundError:
+        raise HandoffJobIdentityValidationError(field_name="job_id", value=job_id, loc="path")
+    except HandoffJobConflictError:
+        raise HandoffJobStatusValidationError(field_name="status", value=data.status, loc="body")

forkflux_api/jobs/helpers.py

@@ -0,0 +1,40 @@
+from forkflux_api.jobs.constants import JobPriorityEnum
+from forkflux_api.jobs.dto import HandoffJobWithArtifacts
+from forkflux_api.jobs.schemas import HandoffJobWithArtifactsItem, JobArtifact
+
+
+def handoff_job_to_response_model(entity: HandoffJobWithArtifacts) -> HandoffJobWithArtifactsItem:
+    job = entity["job"]
+    artifacts = entity["artifacts"]
+
+    return HandoffJobWithArtifactsItem(
+        id=job.job_details.id,
+        parent_job_id=job.job_details.parent_job_id,
+        summary=job.job_details.summary,
+        context_payload=job.job_details.context_payload,
+        status=job.job_details.status,
+        priority=JobPriorityEnum(job.job_details.priority),
+        source_agent_label=job.source_agent_label,
+        assignee_agent_label=job.assignee_agent_label,
+        target_role_key=job.target_role_key,
+        constraints=job.job_details.constraints,
+        artifacts=[
+            JobArtifact(
+                type=artifact.artifact_type,
+                uri=artifact.artifact_uri,
+                checksum=artifact.artifact_checksum,
+                metadata_json=artifact.metadata_json,
+            )
+            for artifact in artifacts
+        ],
+        failure_reason=job.job_details.failure_reason,
+        published_at=job.job_details.published_at,
+        claimed_at=job.job_details.claimed_at,
+        started_at=job.job_details.started_at,
+        completed_at=job.job_details.completed_at,
+        failed_at=job.job_details.failed_at,
+        cancelled_at=job.job_details.cancelled_at,
+        expires_at=job.job_details.expires_at,
+        created_at=job.job_details.created_at,
+        updated_at=job.job_details.updated_at,
+    )