"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.

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

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:
    return {"summary": "..."}

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:
        return {"status": "sent"}

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.

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

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.

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)

result = await executor.call_async(
    "text.summarize", 
    inputs={"text": "..."}, 
    context=context
)

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