forkflux-api 0.1.0__tar.gz

forkflux_api-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+.idea
+.mypy_cache
+.ruff_cache
+.pytest_cache
+.env
+local.yml
+docker_data
+
+AGENTS.md
+.aiginore
+.agents
+.clinerules
+.clineignore
+.roorules
+.roo
+.rooignore
+.zoorules
+.zoo
+.zooignore
+.cursor
+.cursorignore
+.claude
+.kilocodeignore
+.kilo

forkflux_api-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: forkflux-api
+Version: 0.1.0
+Summary: Core API server and coordination bus for cross-device AI agent task handoff.
+Project-URL: Homepage, https://github.com/forkflux/forkflux
+Project-URL: Repository, https://github.com/forkflux/forkflux
+Project-URL: Issues, https://github.com/forkflux/forkflux/issues
+Keywords: agents,ai,coordination,developer-tools,fastapi,handoff,llm,multi-agent,task-delegation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.14
+Requires-Dist: aiosqlite==0.22.1
+Requires-Dist: alembic-postgresql-enum==1.10.0
+Requires-Dist: alembic==1.18.4
+Requires-Dist: asyncpg==0.31.0
+Requires-Dist: fastapi==0.137.2
+Requires-Dist: gunicorn==26.0.0
+Requires-Dist: pydantic-settings==2.14.1
+Requires-Dist: pydantic==2.13.4
+Requires-Dist: sqlalchemy==2.0.51
+Requires-Dist: structlog==26.1.0
+Requires-Dist: typer==0.26.7
+Requires-Dist: uvicorn==0.49.0
+Description-Content-Type: text/markdown
+
+# ForkFlux API
+
+> Core API server and coordination bus for cross-device AI agent task handoff.
+
+ForkFlux API is the stateful coordination layer behind ForkFlux. It gives isolated AI agents a shared, machine-readable job pool for publishing work, atomically claiming tasks, transferring context and artifacts, and closing jobs with explicit lifecycle states.
+
+Use this package when you need the ForkFlux coordination bus service itself: a FastAPI application backed by PostgreSQL or SQLite, plus a small CLI for registering target roles and agent API tokens.
+
+## What it provides
+
+- **Shared handoff queue** for agent-to-agent job delegation.
+- **Atomic claims** so only one agent can own a published job.
+- **Structured context transfer** through job constraints, payloads, and artifacts.
+- **Lifecycle control** for `published` → `in_progress` → `completed` / `failed` / `cancelled`.
+- **Agent identity and role registry** for role-aware routing.
+
+## Package
+
+```bash
+pip install forkflux-api
+```
+
+The installed CLI entry point is:
+
+```bash
+forkflux --help
+```
+
+## Runtime requirements
+
+- Python 3.14+
+
+See the main ForkFlux repository for local Docker setup, MCP integration, and end-to-end handoff examples.

forkflux_api-0.1.0/README.md

@@ -0,0 +1,33 @@
+# ForkFlux API
+
+> Core API server and coordination bus for cross-device AI agent task handoff.
+
+ForkFlux API is the stateful coordination layer behind ForkFlux. It gives isolated AI agents a shared, machine-readable job pool for publishing work, atomically claiming tasks, transferring context and artifacts, and closing jobs with explicit lifecycle states.
+
+Use this package when you need the ForkFlux coordination bus service itself: a FastAPI application backed by PostgreSQL or SQLite, plus a small CLI for registering target roles and agent API tokens.
+
+## What it provides
+
+- **Shared handoff queue** for agent-to-agent job delegation.
+- **Atomic claims** so only one agent can own a published job.
+- **Structured context transfer** through job constraints, payloads, and artifacts.
+- **Lifecycle control** for `published` → `in_progress` → `completed` / `failed` / `cancelled`.
+- **Agent identity and role registry** for role-aware routing.
+
+## Package
+
+```bash
+pip install forkflux-api
+```
+
+The installed CLI entry point is:
+
+```bash
+forkflux --help
+```
+
+## Runtime requirements
+
+- Python 3.14+
+
+See the main ForkFlux repository for local Docker setup, MCP integration, and end-to-end handoff examples.

forkflux_api-0.1.0/forkflux_api/agents/dependencies.py

@@ -0,0 +1,21 @@
+from fastapi import Depends, Request
+from forkflux_api.agents.respositories import TargetRoleRepository
+from forkflux_api.agents.services import TargetRoleService
+from forkflux_api.database import get_session
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+def get_trace_id(request: Request) -> str:
+    return request.state.trace_id
+
+
+def get_target_role_repo(
+    session: AsyncSession = Depends(get_session), trace_id: str = Depends(get_trace_id)
+) -> TargetRoleRepository:
+    return TargetRoleRepository(session=session, trace_id=trace_id)
+
+
+def get_target_role_service(
+    repository: TargetRoleRepository = Depends(get_target_role_repo), trace_id: str = Depends(get_trace_id)
+) -> TargetRoleService:
+    return TargetRoleService(target_role_repo=repository, trace_id=trace_id)

forkflux_api-0.1.0/forkflux_api/agents/dto.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class TargetRoleCreate:
+    role_key: str
+    role_label: str
+
+
+@dataclass(slots=True)
+class AgentIdentityCreate:
+    agent_label: str
+    role_id: int
+    tool_family: str | None
+
+
+@dataclass(slots=True)
+class AgentApiTokenCreate:
+    agent_id: int

forkflux_api-0.1.0/forkflux_api/agents/exceptions.py

@@ -0,0 +1,28 @@
+class AgentApiTokenNotFoundError(Exception):
+    code = "agent_api_token.not_found"
+    msg = "Agent API token not found."
+
+
+class AgentApiTokenConflictError(Exception):
+    code = "agent_api_token.conflict"
+    msg = "Agent API token conflicts with existing data constraints."
+
+
+class AgentIdentityNotFoundError(Exception):
+    code = "agent_identity.not_found"
+    msg = "Agent identity not found."
+
+
+class AgentIdentityConflictError(Exception):
+    code = "agent_identity.conflict"
+    msg = "Agent identity conflicts with existing data constraints."
+
+
+class TargetRoleConflictError(Exception):
+    code = "target_role.conflict"
+    msg = "Target role already exists."
+
+
+class TargetRoleNotFoundError(Exception):
+    code = "target_role.not_found"
+    msg = "Target role not found."

forkflux_api-0.1.0/forkflux_api/agents/handlers.py

@@ -0,0 +1,19 @@
+from fastapi import APIRouter, Depends
+from forkflux_api.agents.dependencies import get_target_role_service
+from forkflux_api.agents.models import AgentIdentity
+from forkflux_api.agents.schemas import GetMeResponse, ListRolesResponse
+from forkflux_api.agents.services import TargetRoleService
+from forkflux_api.dependencies import get_current_agent, verify_token
+
+router = APIRouter(prefix="/agents", tags=["agents"], dependencies=[Depends(verify_token)])
+
+
+@router.get("/roles", response_model=list[ListRolesResponse])
+async def list_roles(service: TargetRoleService = Depends(get_target_role_service)):
+    roles = await service.get_all_roles()
+    return roles
+
+
+@router.get("/me", response_model=GetMeResponse)
+async def get_me(current_agent: AgentIdentity = Depends(get_current_agent)):
+    return current_agent

forkflux_api-0.1.0/forkflux_api/agents/models.py

@@ -0,0 +1,38 @@
+from datetime import datetime
+
+from forkflux_api.database import Base, UTCDateTime
+from sqlalchemy import BigInteger, Boolean, ForeignKey, Integer, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+PK_TYPE = BigInteger().with_variant(Integer, "sqlite")
+
+
+class TargetRole(Base):
+    __tablename__ = "target_role"
+
+    id: Mapped[int] = mapped_column(PK_TYPE, primary_key=True, autoincrement=True)
+    role_key: Mapped[str] = mapped_column(Text, nullable=False, unique=True)
+    role_label: Mapped[str] = mapped_column(Text, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(UTCDateTime(), nullable=False)
+
+
+class AgentIdentity(Base):
+    __tablename__ = "agent_identity"
+
+    id: Mapped[int] = mapped_column(PK_TYPE, primary_key=True, autoincrement=True)
+    agent_label: Mapped[str] = mapped_column(Text, nullable=False)
+    role_id: Mapped[int] = mapped_column(ForeignKey("target_role.id"), nullable=False)
+    tool_family: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(UTCDateTime(), nullable=False)
+
+
+class AgentApiToken(Base):
+    __tablename__ = "agent_api_token"
+
+    id: Mapped[int] = mapped_column(PK_TYPE, primary_key=True, autoincrement=True)
+    token_hash: Mapped[str] = mapped_column(Text, nullable=False, unique=True)
+    agent_id: Mapped[int] = mapped_column(ForeignKey("agent_identity.id"), nullable=False)
+    is_active: Mapped[bool] = mapped_column(Boolean, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(UTCDateTime(), nullable=False)
+    last_used_at: Mapped[datetime | None] = mapped_column(UTCDateTime(), nullable=True)
+    revoked_at: Mapped[datetime | None] = mapped_column(UTCDateTime(), nullable=True)

forkflux_api-0.1.0/forkflux_api/agents/respositories.py

@@ -0,0 +1,150 @@
+from datetime import datetime, timezone
+
+import structlog
+from forkflux_api.agents.dto import AgentApiTokenCreate, AgentIdentityCreate, TargetRoleCreate
+from forkflux_api.agents.exceptions import (
+    AgentApiTokenConflictError,
+    AgentApiTokenNotFoundError,
+    AgentIdentityConflictError,
+    AgentIdentityNotFoundError,
+    TargetRoleConflictError,
+    TargetRoleNotFoundError,
+)
+from forkflux_api.agents.models import AgentApiToken, AgentIdentity, TargetRole
+from sqlalchemy import exists, select, update
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class TargetRoleRepository:
+    def __init__(self, session: AsyncSession, trace_id: str) -> None:
+        self._session = session
+        self._logger = structlog.get_logger().bind(cls=self.__class__.__name__, trace_id=trace_id)
+
+    async def list(self) -> list[TargetRole]:
+        result = await self._session.execute(select(TargetRole))
+        return list(result.scalars().all())
+
+    async def get_by_role_key(self, role_key: str) -> TargetRole:
+        result = await self._session.execute(select(TargetRole).where(TargetRole.role_key == role_key))
+        target_role = result.scalar_one_or_none()
+        if target_role is None:
+            raise TargetRoleNotFoundError
+
+        return target_role
+
+    async def exists(self, role_key: str) -> bool:
+        log = self._logger.bind(method="exists", role_key=role_key)
+        result = await self._session.execute(select(exists().where(TargetRole.role_key == role_key)))
+        role_exists = result.scalar_one()
+
+        if role_exists:
+            log.info("target_role_exists_hit")
+        else:
+            log.info("target_role_exists_miss")
+
+        return role_exists
+
+    async def create(self, dto: TargetRoleCreate) -> TargetRole:
+        target_role = TargetRole(
+            role_key=dto.role_key,
+            role_label=dto.role_label,
+            created_at=datetime.now(timezone.utc),
+        )
+
+        self._session.add(target_role)
+        try:
+            await self._session.flush()
+        except IntegrityError as err:
+            await self._session.rollback()
+            raise TargetRoleConflictError from err
+
+        return target_role
+
+
+class AgentApiTokenRepository:
+    def __init__(self, session: AsyncSession, trace_id: str) -> None:
+        self._session = session
+        self._logger = structlog.get_logger().bind(cls=self.__class__.__name__, trace_id=trace_id)
+
+    async def get(self, token_hash: str) -> AgentApiToken:
+        result = await self._session.execute(
+            select(AgentApiToken).where(
+                AgentApiToken.token_hash == token_hash,
+                AgentApiToken.is_active.is_(True),
+            )
+        )
+        token = result.scalar_one_or_none()
+        if token is None:
+            raise AgentApiTokenNotFoundError
+
+        return token
+
+    async def create(self, dto: AgentApiTokenCreate, token_hash: str) -> AgentApiToken:
+        agent_api_token = AgentApiToken(
+            token_hash=token_hash,
+            agent_id=dto.agent_id,
+            is_active=True,
+            created_at=datetime.now(timezone.utc),
+        )
+
+        self._session.add(agent_api_token)
+        try:
+            await self._session.flush()
+        except IntegrityError as err:
+            await self._session.rollback()
+            raise AgentApiTokenConflictError from err
+
+        return agent_api_token
+
+    async def revoke(self, agent_id: int) -> int:
+        revoked_at = datetime.now(timezone.utc)
+        result = await self._session.execute(
+            update(AgentApiToken)
+            .where(
+                AgentApiToken.agent_id == agent_id,
+                AgentApiToken.is_active.is_(True),
+            )
+            .values(
+                is_active=False,
+                revoked_at=revoked_at,
+            )
+        )
+        await self._session.flush()
+
+        return result.rowcount or 0  # type: ignore[attr-defined]
+
+
+class AgentIdentityRepository:
+    def __init__(self, session: AsyncSession, trace_id: str) -> None:
+        self._session = session
+        self._logger = structlog.get_logger().bind(cls=self.__class__.__name__, trace_id=trace_id)
+
+    async def list(self) -> list[AgentIdentity]:
+        result = await self._session.execute(select(AgentIdentity))
+        return list(result.scalars().all())
+
+    async def get_by_id(self, agent_identity_id: int) -> AgentIdentity:
+        result = await self._session.execute(select(AgentIdentity).where(AgentIdentity.id == agent_identity_id))
+        agent_identity = result.scalar_one_or_none()
+        if agent_identity is None:
+            raise AgentIdentityNotFoundError
+
+        return agent_identity
+
+    async def create(self, dto: AgentIdentityCreate) -> AgentIdentity:
+        agent_identity = AgentIdentity(
+            agent_label=dto.agent_label,
+            role_id=dto.role_id,
+            tool_family=dto.tool_family,
+            created_at=datetime.now(timezone.utc),
+        )
+
+        self._session.add(agent_identity)
+        try:
+            await self._session.flush()
+        except IntegrityError as err:
+            await self._session.rollback()
+            raise AgentIdentityConflictError from err
+
+        return agent_identity

forkflux_api-0.1.0/forkflux_api/agents/schemas.py

@@ -0,0 +1,17 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class ListRolesResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    role_key: str
+    role_label: str
+
+
+class GetMeResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    agent_label: str
+    role_id: int
+    tool_family: str | None

forkflux_api-0.1.0/forkflux_api/agents/services.py

@@ -0,0 +1,117 @@
+import hashlib
+import secrets
+
+import structlog
+from forkflux_api.agents.dto import AgentApiTokenCreate, AgentIdentityCreate, TargetRoleCreate
+from forkflux_api.agents.models import AgentApiToken, AgentIdentity, TargetRole
+from forkflux_api.agents.respositories import AgentApiTokenRepository, AgentIdentityRepository, TargetRoleRepository
+
+
+class TargetRoleService:
+    def __init__(self, target_role_repo: TargetRoleRepository, trace_id: str) -> None:
+        self._logger = structlog.get_logger().bind(cls=self.__class__.__name__, trace_id=trace_id)
+        self._target_role_repo = target_role_repo
+
+    async def get_all_roles(self) -> list[TargetRole]:
+        log = self._logger.bind(method="get_all_roles")
+        log.info("operation_started")
+
+        roles = await self._target_role_repo.list()
+
+        log.info("operation_completed", roles_count=len(roles))
+        return roles
+
+    async def get_by_role_key(self, role_key: str) -> TargetRole:
+        log = self._logger.bind(method="get_by_role_key", role_key=role_key)
+        log.info("operation_started")
+
+        role = await self._target_role_repo.get_by_role_key(role_key)
+
+        log.info("operation_completed")
+        return role
+
+    async def is_role_exists(self, role_key: str) -> bool:
+        log = self._logger.bind(method="is_role_exists", role_key=role_key)
+        log.info("operation_started")
+
+        exists = await self._target_role_repo.exists(role_key)
+
+        log.info("operation_completed", role_exists=exists)
+        return exists
+
+    async def create_role(self, dto: TargetRoleCreate) -> TargetRole:
+        log = self._logger.bind(method="create_role", role_key=dto.role_key)
+        log.info("operation_started")
+
+        role = await self._target_role_repo.create(dto)
+
+        log.info("operation_completed")
+        return role
+
+
+class AgentApiTokenService:
+    def __init__(self, agent_api_token_repo: AgentApiTokenRepository, trace_id: str) -> None:
+        self._logger = structlog.get_logger().bind(cls=self.__class__.__name__, trace_id=trace_id)
+        self._agent_api_token_repo = agent_api_token_repo
+
+    async def get_token(self, token_hash: str) -> AgentApiToken:
+        log = self._logger.bind(method="get_token", token_hash=token_hash)
+        log.info("operation_started")
+
+        token = await self._agent_api_token_repo.get(token_hash)
+
+        log.info("operation_completed", token_id=token.id, agent_id=token.agent_id)
+        return token
+
+    async def create_token(self, dto: AgentApiTokenCreate) -> str:
+        log = self._logger.bind(method="create_token", agent_id=dto.agent_id)
+        log.info("operation_started")
+
+        raw_token = secrets.token_urlsafe(32)
+        token_hash = hashlib.sha256(raw_token.encode()).hexdigest()
+        await self._agent_api_token_repo.create(dto=dto, token_hash=token_hash)
+
+        log.info("operation_completed")
+        return raw_token
+
+    async def revoke_token(self, agent_id: int) -> int:
+        log = self._logger.bind(method="revoke_token", agent_id=agent_id)
+        log.info("operation_started")
+
+        revoked_count = await self._agent_api_token_repo.revoke(agent_id)
+
+        log.info("operation_completed", revoked_count=revoked_count)
+        return revoked_count
+
+
+class AgentIdentityService:
+    def __init__(self, agent_identity_repo: AgentIdentityRepository, trace_id: str) -> None:
+        self._logger = structlog.get_logger().bind(cls=self.__class__.__name__, trace_id=trace_id)
+        self._agent_identity_repo = agent_identity_repo
+
+    async def get_all_agents(self) -> list[AgentIdentity]:
+        log = self._logger.bind(method="get_all_agents")
+        log.info("operation_started")
+
+        agents = await self._agent_identity_repo.list()
+
+        log.info("operation_completed", agents_count=len(agents))
+        return agents
+
+    async def get_by_id(self, agent_identity_id: int) -> AgentIdentity:
+        log = self._logger.bind(method="get_by_id", agent_identity_id=agent_identity_id)
+        log.info("operation_started")
+
+        agent = await self._agent_identity_repo.get_by_id(agent_identity_id)
+
+        log.info("operation_completed")
+        return agent
+
+    async def create_agent(self, dto: AgentIdentityCreate) -> AgentIdentity:
+        log = self._logger.bind(method="create_agent", agent_label=dto.agent_label, role_id=dto.role_id)
+        log.info("operation_started")
+
+        agent = await self._agent_identity_repo.create(dto)
+
+        log.info("operation_completed", agent_identity_id=agent.id)
+        return agent