apcore 0.10.0

Schema-driven module development framework for AI-perceivable interfaces

apcore

Schema-driven module development framework for AI-perceivable interfaces.

apcore provides a unified task orchestration framework with strict type safety, access control, middleware pipelines, and built-in observability. It enables you to define modules with structured input/output schemas that are easily consumed by LLMs and other automated systems.

Features

• Schema-driven modules -- Define input/output contracts using Pydantic models with automatic validation
• 11-step execution pipeline -- Context creation, safety checks, ACL enforcement, approval gate, validation, middleware chains, and execution with timeout support
• @module decorator -- Turn plain functions into fully schema-aware modules with zero boilerplate
• YAML bindings -- Register modules declaratively without modifying source code
• Access control (ACL) -- Pattern-based, first-match-wins rules with wildcard support
• Middleware system -- Composable before/after hooks with error recovery
• Observability -- Tracing (spans), metrics collection, and structured context logging
• Async support -- Seamless sync and async module execution
• Safety guards -- Call depth limits, circular call detection, frequency throttling
• Approval system -- Pluggable approval gate (Step 5) with sync/async handlers, Phase B resume, and audit events
• Extension points -- Unified extension management for discoverers, middleware, ACL, approval handlers, span exporters, and module validators
• Async task management -- Background module execution with status tracking, cancellation, and concurrency limiting
• W3C Trace Context -- traceparent header injection/extraction for distributed tracing interop

Documentation

For full documentation, including Quick Start guides for both Python and TypeScript, visit: https://aipartnerup.github.io/apcore/getting-started.html

Requirements

• Python >= 3.11

Installation

pip install -e .

For development:

pip install -e ".[dev]"

Quick Start

Simple usage (Global Client)

For simple scripts or prototypes, you can use the global apcore functions:

import apcore

@apcore.module(id="math.add", description="Add two integers")
def add(a: int, b: int) -> int:
    return a + b

# Directly call it
result = apcore.call("math.add", {"a": 10, "b": 5})
print(result)  # {'result': 15}

Simplified Client (Recommended)

The APCore client provides a unified entry point that manages everything for you:

from apcore import APCore

client = APCore()

@client.module(id="math.add", description="Add two integers")
def add(a: int, b: int) -> int:
    return a + b

# Call the module
result = client.call("math.add", {"a": 10, "b": 5})
print(result)  # {'result': 15}

Advanced: Define a module with a class

from pydantic import BaseModel
from apcore import Context, APCore

client = APCore()

class GreetInput(BaseModel):
    name: str

class GreetOutput(BaseModel):
    message: str

class GreetModule:
    input_schema = GreetInput
    output_schema = GreetOutput
    description = "Greet a user"

    def execute(self, inputs: dict, context: Context) -> dict:
        return {"message": f"Hello, {inputs['name']}!"}

client.register("greet", GreetModule())
result = client.call("greet", {"name": "Alice"})
# {"message": "Hello, Alice!"}

Add middleware

from apcore import LoggingMiddleware, TracingMiddleware

client.use(LoggingMiddleware())
client.use(TracingMiddleware())

Access control

from apcore import ACL, ACLRule

acl = ACL(rules=[
    ACLRule(callers=["admin.*"], targets=["*"], effect="allow", description="Admins can call anything"),
    ACLRule(callers=["*"], targets=["admin.*"], effect="deny", description="Others cannot call admin modules"),
])
executor = Executor(registry=registry, acl=acl)

Project Structure

src/apcore/
    __init__.py          # Public API
    async_task.py        # Background task manager
    cancel.py            # Cooperative cancellation primitives
    context.py           # Execution context & identity
    executor.py          # Core execution engine
    decorator.py         # @module decorator
    bindings.py          # YAML binding loader
    config.py            # Configuration
    acl.py               # Access control
    approval.py          # Approval system
    extensions.py        # Extension point manager
    errors.py            # Error hierarchy
    module.py            # Module annotations & metadata
    trace_context.py     # W3C trace context helpers
    middleware/          # Middleware system
    observability/       # Tracing, metrics, logging
    registry/            # Module discovery & registration
    schema/              # Schema loading, validation, export
    utils/               # Utilities

Development

Run tests

pytest

Run tests with coverage

pytest --cov=src/apcore --cov-report=html

Lint and format

ruff check --fix src/ tests/
ruff format src/ tests/

Type check

mypy src/ tests/

📄 License

Apache-2.0

🔗 Links

• Documentation: docs/apcore - Complete documentation
• Website: aipartnerup.com
• GitHub: aipartnerup/apcore-python
• PyPI: apcore
• Issues: GitHub Issues
• Discussions: GitHub Discussions