ploston-core 1.4.0.dev1770438724

Core engine for Ploston - Deterministic Agent Execution Layer

ploston-core

Core engine for Ploston - Deterministic Agent Execution Layer.

Overview

ploston-core contains the shared engine components that both OSS and Enterprise packages depend on. It provides:

Module	Description
Engine	Workflow execution engine with sequential, deterministic execution
Registry	Tool and workflow registries with auto-discovery
MCP	Model Context Protocol client connections
MCP Frontend	MCP server frontend (stdio/HTTP transport)
API	REST API framework (FastAPI-based)
Sandbox	Python sandbox with 7-layer security model
Template	Jinja2 template engine for parameter rendering
Telemetry	Structured logging and metrics
Config	Layered configuration with hot-reload
Errors	Structured, actionable error handling
Plugins	Extensible plugin framework

Installation

pip install ploston-core

Or with uv:

uv add ploston-core

Quick Start

from ploston_core.engine import Engine
from ploston_core.registry import ToolRegistry

# Create engine with tool registry
registry = ToolRegistry()
engine = Engine(registry=registry)

# Execute workflow
result = await engine.execute(workflow)

Documentation

Detailed documentation is available in the docs/ directory:

Concepts

• How Ploston Works - Architecture overview and design principles
• Execution Model - How workflows execute step-by-step
• Security Model - 7-layer sandbox security for code execution

Reference

• Workflow Schema - Complete YAML schema for defining workflows
• Configuration Reference - All configuration options
• Error Codes - Error codes and troubleshooting guide

Architecture

• Implemented Architecture - Current architecture summary

Development

Prerequisites

• Python 3.12+
• uv (recommended)

Setup

# Clone the repository
git clone https://github.com/ostanlabs/ploston-core.git
cd ploston-core

# Install dependencies
uv sync

# Run tests
uv run pytest tests/unit/ -v

# Run linting
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

Running Tests

# Unit tests
uv run pytest tests/unit/ -v

# With coverage
uv run pytest tests/unit/ -v --cov=ploston_core --cov-report=term-missing

Related Packages

Package	Description
ploston	OSS distribution (core + CLI)
ploston-cli	Command-line interface
ploston-enterprise	Enterprise features

License

Apache-2.0 - see LICENSE for details.