kubiya-control-plane-api 0.9.15__py3-none-any.whl

control_plane_api/README.md

@@ -0,0 +1,350 @@
+# Kubiya Control Plane API
+
+A multi-tenant AI agent orchestration and management platform built with FastAPI, Temporal, and PostgreSQL.
+
+## Features
+
+- **Multi-tenant Architecture**: Manage multiple projects, teams, and agents
+- **Workflow Orchestration**: Temporal-based workflow execution
+- **Flexible Agent Runtime**: Support for multiple agent types and skills
+- **Policy Enforcement**: OPA-based policy engine for agent governance
+- **Tool Call Enforcement**: Non-blocking validation of tool executions against policies
+- **Event Bus System**: Pluggable multi-provider event streaming (HTTP, Redis, WebSocket, NATS)
+- **Scalable Workers**: Distributed worker architecture for agent execution
+- **Context Management**: Environment and team-specific context handling
+- **LLM Integration**: Support for multiple LLM providers via LiteLLM
+- **Comprehensive APIs**: RESTful APIs for all platform features
+
+### Tool Call Enforcement
+
+The platform includes **end-to-end tool call enforcement** that validates agent tool executions against OPA policies:
+
+- **Non-blocking enforcement**: Policy violations are injected into tool outputs without failing workflows
+- **Fail-open strategy**: Graceful degradation on timeout or error prevents blocking workflows
+- **Automatic risk assessment**: Tools classified as critical/high/medium/low risk
+- **Full context enrichment**: User, organization, team, and environment data included in policy evaluation
+- **5 example policies**: Role-based access, production safeguards, bash validation, business hours, MCP allowlist
+
+See the [Tool Enforcement Guide](../docs/TOOL_ENFORCEMENT.md) for detailed documentation.
+
+### Event Bus System
+
+The platform includes a **production-grade event bus abstraction** for real-time event streaming:
+
+- **Multi-provider support**: HTTP, Redis, WebSocket, NATS
+- **Parallel publishing**: Events sent to all providers simultaneously
+- **Graceful degradation**: Continues if one provider fails
+- **Optional dependencies**: Lightweight base package with optional providers
+- **Comprehensive logging**: Structured JSON logs at every step
+- **Health monitoring**: Per-provider and overall system health checks
+- **Backwards compatible**: Falls back to direct Redis if not configured
+
+**Quick Start:**
+
+```bash
+# Base package (HTTP, Redis, WebSocket)
+pip install kubiya-control-plane-api
+
+# With YAML config support
+pip install kubiya-control-plane-api[yaml]
+
+# With NATS provider
+pip install kubiya-control-plane-api[nats]
+
+# All event bus features
+pip install kubiya-control-plane-api[event-bus]
+```
+
+**Configuration Example:**
+
+```yaml
+# config.yaml
+event_bus:
+  http:
+    enabled: true
+    base_url: http://localhost:8000
+  redis:
+    enabled: true
+    redis_url: redis://localhost:6379
+```
+
+See the [Event Bus README](app/lib/event_bus/README.md) for detailed documentation.
+
+## Installation
+
+### Using pip
+
+```bash
+pip install kubiya-control_plane_api
+```
+
+### From source
+
+```bash
+git clone https://github.com/kubiyabot/agent-control-plane.git
+cd agent-control-plane/control_plane_api
+pip install -e .
+```
+
+### With development dependencies
+
+```bash
+pip install kubiya-control_plane_api[dev]
+```
+
+## Quick Start
+
+### 1. Set up environment variables
+
+Create a `.env` file or set the following environment variables:
+
+```bash
+# Database Configuration
+DATABASE_URL=postgresql://user:password@localhost:5432/control_plane
+
+# Supabase (for serverless deployments)
+SUPABASE_URL=your-supabase-url
+SUPABASE_KEY=your-supabase-key
+
+# Temporal Configuration
+TEMPORAL_HOST=localhost:7233
+TEMPORAL_NAMESPACE=default
+
+# API Configuration
+API_TITLE="Agent Control Plane"
+API_VERSION="1.0.0"
+ENVIRONMENT=development
+LOG_LEVEL=info
+
+# Security
+SECRET_KEY=your-secret-key-here
+
+# Optional: Kubiya Integration
+KUBIYA_API_KEY=your-kubiya-api-key
+KUBIYA_API_URL=https://api.kubiya.ai
+
+# Optional: Event Bus Configuration (or use YAML config)
+EVENT_BUS_HTTP_ENABLED=true
+EVENT_BUS_HTTP_BASE_URL=http://localhost:8000
+EVENT_BUS_REDIS_ENABLED=true
+```
+
+**Alternatively, use YAML configuration** (recommended):
+
+Create `config.yaml` or set `KUBIYA_CONFIG_FILE=/path/to/config.yaml`:
+
+```yaml
+event_bus:
+  http:
+    enabled: true
+    base_url: http://localhost:8000
+    batching_enabled: true
+  redis:
+    enabled: true
+    redis_url: redis://localhost:6379
+```
+
+### 2. Run database migrations
+
+```bash
+alembic upgrade head
+```
+
+### 3. Start the API server
+
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port 7777 --reload
+```
+
+The API will be available at `http://localhost:7777`
+
+### 4. Access the API documentation
+
+Open your browser and navigate to:
+- Swagger UI: `http://localhost:7777/api/docs`
+- ReDoc: `http://localhost:7777/api/redoc`
+
+### 5. Start a worker (optional)
+
+To process agent execution workflows:
+
+```bash
+python worker.py
+```
+
+## Package Structure
+
+```
+app/
+├── activities/          # Temporal activities
+├── lib/                # Client libraries and utilities
+│   ├── event_bus/      # Event bus abstraction (multi-provider)
+│   │   ├── base.py     # Provider interface
+│   │   ├── manager.py  # Manager orchestrator
+│   │   └── providers/  # HTTP, Redis, WebSocket, NATS providers
+│   ├── redis_client.py # Redis connection
+│   └── temporal_client.py # Temporal connection
+├── middleware/         # FastAPI middleware (auth, etc.)
+├── models/             # SQLAlchemy models
+├── policies/           # OPA policy files (.rego)
+├── routers/            # FastAPI route handlers
+├── services/           # Business logic services
+├── skills/             # Agent skills
+├── workflows/          # Temporal workflows
+├── config.py           # Configuration management
+├── database.py         # Database connection
+└── main.py             # FastAPI application entry point
+```
+
+## API Endpoints
+
+### Core Resources
+
+- **Projects**: `/api/v1/projects` - Multi-project management
+- **Environments**: `/api/v1/environments` - Environment configuration
+- **Agents**: `/api/v1/agents` - Agent management
+- **Teams**: `/api/v1/teams` - Team management
+- **Workflows**: `/api/v1/workflows` - Workflow definitions
+- **Executions**: `/api/v1/executions` - Execution tracking
+- **Workers**: `/api/v1/workers` - Worker registration and management
+
+### Skills and Policies
+
+- **Skills**: `/api/v1/skills` - Tool sets and definitions
+- **Policies**: `/api/v1/policies` - Policy management and enforcement
+
+### Integration
+
+- **Secrets**: `/api/v1/secrets` - Secrets management (proxies to Kubiya)
+- **Integrations**: `/api/v1/integrations` - Third-party integrations
+- **Models**: `/api/v1/models` - LLM model configuration
+
+### Utilities
+
+- **Health**: `/api/health` - Health check endpoint
+- **Event Bus Health**: `/api/health/event-bus` - Event bus provider health
+- **Task Planning**: `/api/v1/task-planning` - AI-powered task planning
+
+## Configuration
+
+The application uses Pydantic Settings for configuration management. All settings can be configured via environment variables or a `.env` file.
+
+### Key Configuration Options
+
+- `DATABASE_URL`: PostgreSQL connection string
+- `SUPABASE_URL`, `SUPABASE_KEY`: Supabase configuration for serverless
+- `TEMPORAL_HOST`: Temporal server address
+- `KUBIYA_API_KEY`: Kubiya platform API key
+- `SECRET_KEY`: Secret key for JWT token signing
+- `LOG_LEVEL`: Logging level (debug, info, warning, error)
+- `ENVIRONMENT`: Deployment environment (development, staging, production)
+
+## Development
+
+### Install development dependencies
+
+```bash
+pip install -e ".[dev]"
+```
+
+### Run tests
+
+```bash
+# All tests
+pytest
+
+# Unit tests only
+pytest -m unit
+
+# Integration tests
+pytest -m integration
+
+# With coverage
+pytest --cov=app --cov-report=html
+```
+
+### Code formatting
+
+```bash
+# Format code with black
+black .
+
+# Lint with ruff
+ruff check .
+```
+
+### Database migrations
+
+```bash
+# Create a new migration
+alembic revision --autogenerate -m "Description of changes"
+
+# Apply migrations
+alembic upgrade head
+
+# Rollback migration
+alembic downgrade -1
+```
+
+## Deployment
+
+### Docker
+
+```bash
+docker build -t control_plane_api .
+docker run -p 7777:7777 --env-file .env control_plane_api
+```
+
+### Vercel (Serverless)
+
+The API is configured for Vercel deployment with `vercel.json` and the Mangum adapter.
+
+```bash
+vercel deploy
+```
+
+## Architecture
+
+### Workflow Orchestration
+
+The platform uses Temporal for reliable workflow execution:
+- Durable execution with automatic retries
+- Activity-based task decomposition
+- Support for long-running workflows
+- Built-in observability and monitoring
+
+### Multi-tenancy
+
+- **Projects**: Top-level isolation boundary
+- **Environments**: Isolated execution contexts within projects
+- **Teams**: Collaborative agent groups
+- **Agents**: Individual agent instances
+
+### Worker Architecture
+
+Workers pull tasks from environment-specific queues and execute agent workflows using Temporal.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests and linting
+5. Submit a pull request
+
+## License
+
+GNU Affero General Public License v3.0 (AGPL-3.0) - see LICENSE file for details
+
+## Support
+
+For issues and questions:
+- GitHub Issues: https://github.com/kubiyabot/agent-control-plane/issues
+- Email: support@kubiya.ai
+
+## Links
+
+- [Documentation](https://github.com/kubiyabot/agent-control-plane/blob/main/README.md)
+- [GitHub Repository](https://github.com/kubiyabot/agent-control-plane)
+- [Kubiya Platform](https://kubiya.ai)
+

control_plane_api/__init__.py

@@ -0,0 +1,4 @@
+"""Kubiya Control Plane API"""
+from control_plane_api.version import __version__, get_sdk_version
+
+__all__ = ["__version__", "get_sdk_version"]

control_plane_api/__version__.py

@@ -0,0 +1,8 @@
+"""DEPRECATED: Use control_plane_api.version instead
+
+This file is kept for backward compatibility only.
+All new code should import from control_plane_api.version
+"""
+from control_plane_api.version import get_sdk_version, __version__
+
+__all__ = ["__version__", "get_sdk_version"]

control_plane_api/alembic/README

@@ -0,0 +1 @@
+Generic single-database configuration.

control_plane_api/alembic/env.py

@@ -0,0 +1,121 @@
+from logging.config import fileConfig
+
+from sqlalchemy import engine_from_config
+from sqlalchemy import pool
+
+from alembic import context
+
+# Import application settings and models
+import sys
+from pathlib import Path
+
+# Add parent directory to path so control_plane_api is importable
+# env.py location: /app/control_plane_api/alembic/env.py
+# We need: /app (which is parent.parent.parent)
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
+
+from control_plane_api.app.config import settings
+from control_plane_api.app.database import Base
+
+from control_plane_api.app.models.project import Project, ProjectStatus
+from control_plane_api.app.models.agent import Agent, AgentStatus, RuntimeType as AgentRuntimeType
+from control_plane_api.app.models.team import Team, TeamStatus, RuntimeType as TeamRuntimeType
+from control_plane_api.app.models.session import Session
+from control_plane_api.app.models.execution import Execution, ExecutionStatus, ExecutionType, ExecutionTriggerSource
+from control_plane_api.app.models.execution_transition import ExecutionTransition
+from control_plane_api.app.models.environment import Environment, EnvironmentStatus
+from control_plane_api.app.models.associations import AgentEnvironment, TeamEnvironment, ExecutionParticipant, ParticipantRole
+from control_plane_api.app.models.job import Job, JobExecution, JobStatus, JobTriggerType, ExecutorType, PlanningMode
+from control_plane_api.app.models.skill import Skill, SkillAssociation, SlashCommand, SlashCommandExecution, SkillType, SkillEntityType, SlashCommandStatus
+from control_plane_api.app.models.worker import Worker, WorkerHeartbeat, WorkerQueue, OrchestrationServer, OrchestrationServerHealth, WorkerStatus, WorkerRegistrationStatus, QueueStatus, ServerHealthStatus
+from control_plane_api.app.models.orchestration import Namespace
+from control_plane_api.app.models.context import AgentContext, EnvironmentContext, ProjectContext, TeamContext, ContextResource
+from control_plane_api.app.models.analytics import ExecutionTurn, ExecutionToolCall, ExecutionTask
+from control_plane_api.app.models.project_management import Profile, ProjectAgent, ProjectTeam
+from control_plane_api.app.models.llm_model import LLMModel
+from control_plane_api.app.models.presence import UserPresence
+from control_plane_api.app.models.workflow import Workflow
+from control_plane_api.app.models.system_tables import (PolicyAssociation)
+# NOTE: auth_user is NOT imported because auth.users is an external table managed by Supabase
+# The foreign key from profiles uses use_alter=True to handle the reference
+from control_plane_api.app.models.workspace import Workspace
+from control_plane_api.app.models.user_profile import UserProfile
+from control_plane_api.app.models.plan_execution import PlanExecution, PlanExecutionStatus
+from control_plane_api.app.models.trace import Trace, Span, TraceStatus, SpanKind, SpanStatusCode
+from control_plane_api.app.models.custom_integration import CustomIntegration, CustomIntegrationStatus
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Override sqlalchemy.url with our DATABASE_URL from settings
+if settings.database_url:
+    # Escape % characters for ConfigParser (% -> %%)
+    escaped_url = settings.database_url.replace("%", "%%")
+    config.set_main_option("sqlalchemy.url", escaped_url)
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# add your model's MetaData object here
+# for 'autogenerate' support
+target_metadata = Base.metadata
+
+# other values from the config, defined by the needs of env.py,
+# can be acquired:
+# my_important_option = config.get_main_option("my_important_option")
+# ... etc.
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode.
+
+    In this scenario we need to create an Engine
+    and associate a connection with the context.
+
+    """
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection, target_metadata=target_metadata
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

control_plane_api/alembic/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}

control_plane_api/alembic/versions/2613c65c3dbe_initial_database_setup.py

@@ -0,0 +1,32 @@
+"""initial_database_setup
+
+Revision ID: 2613c65c3dbe
+Revises: 
+Create Date: 2025-11-18 15:17:49.174839
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '2613c65c3dbe'
+down_revision: Union[str, Sequence[str], None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # Create PostgreSQL extensions required for the application
+    op.execute('CREATE EXTENSION IF NOT EXISTS "uuid-ossp"')
+    op.execute('CREATE EXTENSION IF NOT EXISTS "pg_trgm"')
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # Drop PostgreSQL extensions
+    op.execute('DROP EXTENSION IF EXISTS "pg_trgm"')
+    op.execute('DROP EXTENSION IF EXISTS "uuid-ossp"')

control_plane_api/alembic/versions/2df520d4927d_merge_heads.py

@@ -0,0 +1,28 @@
+"""merge_heads
+
+Revision ID: 2df520d4927d
+Revises: add_model_type_to_llm_models, 91520433aafc
+Create Date: 2025-12-08 14:55:51.006126
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '2df520d4927d'
+down_revision: Union[str, Sequence[str], None] = ('add_model_type_to_llm_models', '91520433aafc')
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    pass
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    pass

control_plane_api/alembic/versions/43abf98d6a01_add_paused_status_to_executions.py

@@ -0,0 +1,73 @@
+"""add_paused_status_to_executions
+
+Adds PAUSED status to the executionstatus enum type,
+enabling pause/resume functionality for executions.
+
+Revision ID: 43abf98d6a01
+Revises: 2df520d4927d
+Create Date: 2025-12-08 14:55:54.974711
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '43abf98d6a01'
+down_revision: Union[str, Sequence[str], None] = '2df520d4927d'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """
+    Add 'paused' value to executionstatus enum.
+
+    Note: The status column in the executions table is actually String(50) in the ORM,
+    but we add this to the enum type for database-level validation if it exists.
+    """
+
+    op.execute("""
+        DO $$
+        BEGIN
+            -- Check if executionstatus enum type exists
+            IF EXISTS (SELECT 1 FROM pg_type WHERE typname = 'executionstatus') THEN
+                -- Check if 'paused' value doesn't already exist
+                IF NOT EXISTS (
+                    SELECT 1 FROM pg_enum
+                    WHERE enumlabel = 'paused'
+                    AND enumtypid = (SELECT oid FROM pg_type WHERE typname = 'executionstatus')
+                ) THEN
+                    ALTER TYPE executionstatus ADD VALUE 'paused';
+                    RAISE NOTICE 'Added "paused" value to executionstatus enum';
+                ELSE
+                    RAISE NOTICE '"paused" value already exists in executionstatus enum';
+                END IF;
+            ELSE
+                RAISE NOTICE 'executionstatus enum does not exist (column is String type) - no action needed';
+            END IF;
+        END $$;
+    """)
+
+    # Update type comment
+    op.execute("""
+        DO $$
+        BEGIN
+            IF EXISTS (SELECT 1 FROM pg_type WHERE typname = 'executionstatus') THEN
+                COMMENT ON TYPE executionstatus IS
+                    'Execution status: pending, running, waiting_for_input, paused, completed, failed, cancelled';
+            END IF;
+        END $$;
+    """)
+
+
+def downgrade() -> None:
+    """
+    Downgrade is not supported for enum value additions.
+
+    PostgreSQL does not support removing enum values without recreating
+    the type, which would require table recreation and downtime.
+    """
+    pass

control_plane_api/alembic/versions/6289854264cb_merge_multiple_heads.py

@@ -0,0 +1,28 @@
+"""merge_multiple_heads
+
+Revision ID: 6289854264cb
+Revises: 6a4d4dc3d8dc, add_plan_executions, add_user_info_to_traces
+Create Date: 2026-01-15 09:03:43.072711
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '6289854264cb'
+down_revision: Union[str, Sequence[str], None] = ('6a4d4dc3d8dc', 'add_plan_executions', 'add_user_info_to_traces')
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    pass
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    pass