"Pythonic AI: Mastering the apcore-python SDK"

Python is the undisputed language of the AI era. It’s the language of research, the language of LLM orchestration (LangChain, CrewAI), and for many, the language of the enterprise backend.

When we designed the apcore-python SDK, our goal was simple: High Perceptibility, Low Intrusion. We wanted to give Python developers a way to make their code "AI-ready" without forcing them to rewrite their entire architecture.

In this nineteenth article of our series, we move from the engine room to the keyboard, showing you how to master the Python SDK to build professional, AI-Perceivable modules.

Defining Modules: The Two Styles

Every developer has a different preference. Some love the structure of classes; others prefer the simplicity of decorators. apcore supports both.

1. The Decorator Style (Fast & Functional)

If you have an existing utility function and you want to turn it into an AI "Skill" in 30 seconds, use the @module decorator.

from apcore import module

@module(id="text.summarize", description="Summarize text for Agentic planning.")
def summarize(text: str, length: int = 100) -> dict:
    # Your logic here...
    return {"summary": "..."}

2. The Class Style (Structured & Extensible)

For modules that require complex state, custom initialization, or detailed behavioral annotations, the class-based approach is superior.

from apcore import Module, ModuleAnnotations, Context
from pydantic import BaseModel

class SendEmailInput(BaseModel):
    to: str
    body: str

class SendEmailModule(Module):
    input_schema = SendEmailInput
    description = "Send secure internal emails."
    annotations = ModuleAnnotations(destructive=False, requires_approval=True)

    def execute(self, inputs: dict, context: Context) -> dict:
        # Business logic...
        return {"status": "sent"}

Pydantic Integration: The Secret Weapon

The "Killer Feature" of apcore-python is its deep integration with Pydantic V2.

In the AI world, your schema's description fields are just as important as the types. apcore-python extracts these descriptions directly from your Pydantic models.

class SearchInput(BaseModel):
    query: str = Field(..., description="The search term. Use keywords, not sentences.")
    limit: int = Field(5, description="Max results to return.")

When you register this module, apcore automatically generates a JSON Schema Draft 2020-12 that includes these descriptions. This ensures that the AI Agent knows exactly how to use each parameter.

Initializing the Core

Starting with v0.18.0, we’ve simplified the APCore constructor to focus on a unified configuration model. You no longer pass multiple paths to the constructor; instead, you load a Config object.

from apcore import APCore, Config

# Load config from apcore.yaml and initialize
config = Config.load("apcore.yaml")
app = APCore(config=config)

This ensures that your security policies, pipeline steps, and registry settings are always in sync across your entire application.

Execution & Async Support

AI Agents are often used in asynchronous environments (web servers, background tasks). The apcore-python SDK is built for this. You can call modules synchronously or asynchronously with full trace propagation.

executor = Executor(registry)

# Async execution with identity propagation
result = await executor.call_async(
    "text.summarize", 
    inputs={"text": "..."}, 
    context=context
)

Conclusion: Built for Developers, Ready for AI

apcore-python isn't just a library; it’s a design pattern. It allows you to build software that is idiomatic for Python developers and perfectly perceivable by AI Agents. By combining the power of Pydantic with the rigor of the apcore protocol, you are building the foundation for a reliable Agentic workforce.

Now that we’ve mastered Python, it’s time to look at the other side of the stack. In our next article, we dive into Type-Safe Agents: Leveraging apcore-js in TypeScript.

This is Article #19 of the **Building the AI-Perceivable World* series. Idiomatic code is the bridge to better AI.*

GitHub: aiperceivable/apcore-python