DEV Community: tercel

Type-Safe Agents: Leveraging apcore-js in TypeScript

tercel — Sat, 06 Jun 2026 12:32:25 +0000

While Python dominates the AI research space, TypeScript is the engine of the modern full-stack web. From high-performance Node.js backends to complex React frontends, TypeScript provides the structure and safety that large-scale engineering teams demand.

When we built the apcore-js SDK, we didn't just want to "port" the Python logic. We wanted to create a first-class, type-safe experience that leverages the unique strengths of the JavaScript ecosystem.

In this twentieth article of our series, we explore how to build AI-Perceivable modules in TypeScript using apcore and TypeBox.

The Goal: Cross-Language Parity

A core tenet of the apcore protocol is that a module’s behavior should be identical regardless of the implementation language. A module named executor.user.get must accept the same JSON input and produce the same output in both Python and TypeScript.

apcore-js achieves this by using TypeBox as its core schema engine. TypeBox allows us to define JSON Schemas that double as TypeScript types, giving us compile-time safety and runtime validation in a single definition.

Defining Type-Safe Schemas

In apcore-js, you define your module's contract using TypeBox's Static and Type primitives:

import { Type, Static } from '@sinclair/typebox';

export const InputSchema = Type.Object({
  userId: Type.String({ description: "The unique UUID of the user." }),
  includePrivate: Type.Boolean({ default: false, description: "Whether to include sensitive fields." })
});

export type Input = Static<typeof InputSchema>;

By adding the description field directly into the TypeBox definition, you are creating the "Cognitive Interface" for the AI while simultaneously providing type hints for your IDE.

Building the Module

apcore-js supports both class-based and functional module definitions. The class-based approach is idiomatic for TypeScript developers:

import { ClassModule, ModuleAnnotations, Context } from '@apcore/core';

export class GetUserModule extends ClassModule {
  id = "executor.user.get";
  description = "Retrieve detailed user profiles.";
  inputSchema = InputSchema;

  annotations = new ModuleAnnotations({
    readonly: true,
    destructive: false
  });

  async execute(inputs: Input, context: Context): Promise<object> {
    // inputs is fully typed!
    const user = await db.users.findUnique({ where: { id: inputs.userId } });
    return { status: "success", user };
  }
}

Automated Discovery & Mapping

Managing a registry in Node.js is just as easy as in Python. apcore-js includes a FileSystemLoader that scans your directory structure.

One of the cleverest parts of the SDK is its Automatic ID Normalization. In TypeScript, it’s common to name your files using camelCase (e.g., sendEmail.ts). apcore-js automatically maps this to the canonical snake_case (e.g., send_email) required by the protocol. This ensures that an AI Agent sees a consistent naming convention even in a polyglot environment.

Trace Propagation in the Node Mesh

AI Agents in the Node ecosystem often live inside microservices. apcore-js is built for distributed environments. It automatically propagates the trace_id through Promise chains and can integrate with existing tracing headers (like Zipkin or Jaeger) via custom middleware.

const result = await executor.callAsync("executor.user.get", { userId: "123" }, context);

Conclusion: Reliability at Compile Time

By combining the rigor of the apcore protocol with the safety of TypeScript and TypeBox, apcore-js allows you to build AI-Perceivable systems that are as reliable as they are intelligent. You get the best of both worlds: high-velocity development and rock-solid architectural constraints.

Now that we’ve mastered the two most popular languages for AI, it’s time to look at the performance tier. In our next article, we dive into Zero-Cost Abstraction: Building High-Performance AI Modules in Rust.

This is Article #20 of the **Building the AI-Perceivable World* series. Type safety is the first step to AI safety.*

GitHub: aiperceivable/apcore-typescript

Pythonic AI: Mastering the apcore-python SDK

tercel — Wed, 03 Jun 2026 12:36:55 +0000

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

apcore-toolkit: The Utility Backbone for Module Developers

tercel — Mon, 01 Jun 2026 14:31:11 +0000

In our previous articles, we’ve looked at the massive ecosystem of adapters (MCP, A2A, CLI) and the rigorous 11-step execution engine. But as an ecosystem grows, a new problem emerges: Maintenance.

Every web framework—Django, Flask, FastAPI, NestJS—needs its own apcore adapter. If each of these adapters were built from scratch, the ecosystem would quickly become a fragmented mess of duplicated logic and inconsistent behavior.

At apcore, we solve this with the apcore-toolkit. It is the shared DNA that powers every scanner and writer in our universe. In this eighteenth article, we look at the utility backbone that makes building for apcore a seamless experience.

Don't Reinvent the Scanner

The core challenge of an apcore adapter is "Perception"—how do you scan an existing codebase and extract its metadata?

The apcore-toolkit provides a framework-agnostic BaseScanner. This class handles the "dirty work" of:

Filtering & Deduplication: Ensuring you don't register the same module twice.
Path Resolution: Mapping complex file structures to Canonical IDs.
Schema Extraction: Merging OpenAPI query, path, and request body parameters into a single, unified JSON Schema.

By using the toolkit, building a new framework adapter moves from a "one-month task" to a "one-day task."

Convention Module Discovery (§5.14)

One of the "magic" features of the toolkit is the ConventionScanner. This is what powers the "Zero Import" way to build modules.

It scans a directory of plain Python files and uses PEP 484 Type Hints to infer the AI-Perceivable contract.

A function def deploy(env: str) automatically generates a schema with an env string property.
The function's docstring is extracted as the module's description.
Module-level constants like CLI_GROUP or TAGS are used to populate surface-specific metadata.

This ensures that developers can focus on business logic while the toolkit handles the "Perceptibility" layer.

The Display Overlay System (§5.13)

How do you change the "Alias" of a module for the MCP surface without changing your source code? You use the DisplayResolver provided by the toolkit.

The toolkit implements a sparse "Display Overlay" logic. It can read a .binding.yaml file and merge its display fields into your scanned modules.

It handles the Sanitization of names (e.g., ensuring MCP tool names are valid).
It follows a strict Resolution Chain: Surface-specific override > Display default > Binding default > Scanner value.

AIEnhancer: The Lazy Developer’s Best Friend

Perhaps the most forward-looking component of the toolkit is the AIEnhancer.

We know that legacy code is often poorly documented. Parameters are named data or arg1, and descriptions are missing. The AIEnhancer uses Small Language Models (SLMs) to:

Read your source code.
Infer the intent of the parameters.
Generate high-quality, AI-ready descriptions and examples.

It transforms "Silent Code" into "AI-Perceivable Skills" automatically.

Conclusion: Velocity Through Standardization

The apcore-toolkit is the silent engine that powers the ecosystem's velocity. By standardizing the "how" of scanning and writing, it ensures that every implementation—whether it’s for a Python CLI or a Rust microservice—behaves with identical rigor.

Now that we’ve seen the toolkit, it’s time to get hands-on. In our next article, we dive into Pythonic AI: Mastering the apcore-python SDK.

This is Article #18 of the **Building the AI-Perceivable World* series. Join us in building the infrastructure for the next decade.*

GitHub: aiperceivable/apcore-toolkit

Observability 2.0: Tracing AI "Thought Chains" with OpenTelemetry

tercel — Sun, 31 May 2026 02:43:33 +0000

"Why did the Agent do that?"

If you are building Agentic systems today, this is the question that keeps you up at night. AI Agents are inherently non-deterministic. They loop, they reason, and they call multiple tools in sequences that are hard to predict. When a multi-step task fails, a traditional stack trace is useless. You don't just need to know where the code crashed; you need to know what the AI was thinking.

In this seventeenth article, and the conclusion of our Engine volume, we explore how apcore integrates with OpenTelemetry (OTel) to turn the "Black Box" of AI reasoning into a transparent, traceable "Glass Box."

The Concept of the "Thought Span"

In traditional distributed tracing, a "Span" represents a single unit of work—like an HTTP request or a database query. In apcore, we introduce the Thought Span.

Every time the Executor.call() method is triggered, apcore automatically wraps the execution in an OpenTelemetry span. This span isn't just a timer; it’s a rich container of AI-specific metadata:

Input/Output Data: What did the AI send, and what did the module return? (Sensitive data is automatically redacted).
ACL Decisions: Which rule allowed or denied this call?
Approval Events: Did a human intervene? How long did the Agent wait?
AI Guidance: If an error occurred, what self-healing instructions were sent back to the model?

Distributed Tracing: From LLM to DB

One of the most powerful features of apcore is its ability to propagate the trace_id across network boundaries.

Imagine a user makes a request to your web frontend. That request enters a fastapi-apcore adapter, triggers an Orchestrator Agent, which then calls a tool module, which finally queries a PostgreSQL database.

Because apcore is W3C Trace-Context compatible, the same trace_id is carried through the entire journey. When you open a tool like Jaeger, Grafana Tempo, or Honeycomb, you don't just see system logs. You see the entire "Thought Chain" of the AI connected to the actual system performance.

Metrics for the Agentic Era

Tracing tells you the Why; Metrics tell you the How Much. apcore exposes Prometheus-ready metrics that give you a bird's-eye view of your Agentic workforce:

Execution Count: Which tools are the AI's "favorites"? (Useful for optimizing frequently used paths).
Latency by Module: Is the AI's reasoning being slowed down by a specific legacy API?
Hallucination Rate (Error Rate): How often does the AI send malformed inputs to a specific module? A high schema validation error rate is a signal that your module's description or documentation needs improvement.

Implementation: One-Line Observability

Enabling this deep insight doesn't require complex boilerplate. In most apcore SDKs, it’s a matter of registering the TracingMiddleware:

from apcore import Executor
from apcore.observability.tracing import TracingMiddleware

executor = Executor(registry)
executor.add_middleware(TracingMiddleware()) # Now everything is traceable

By standardizing observability at the protocol level, we ensure that every implementation—whether in Python, Rust, or TS—contributes to the same global visibility.

Conclusion: Engineering Transparency

Reliability in the Agentic Era is impossible without transparency. apcore Observability 2.0 bridges the gap between software engineering and AI reasoning. It gives SREs and Developers the tools they need to monitor, debug, and optimize autonomous systems with professional precision.

Summary of Volume II: The Engine

We have now deconstructed the core of apcore:

We looked at the Discovery Algorithm (Directory-as-ID).
We traced the 11-step Execution Pipeline.
We explored Strict Schemas and Behavioral Annotations.
We secured the system with Pattern-Based ACL and Approval Gates.
And finally, we made it all visible with OpenTelemetry.

Now that you understand the Engine, it’s time to build. In Volume III, we’ll move to Practical Implementation, starting with the apcore-toolkit: the Swiss Army Knife for module developers.

This is Article #17 of the **Building the AI-Perceivable World* series. Transparency is the bedrock of Trust.*

GitHub: aiperceivable/apcore

Human-in-the-Loop: The Runtime Enforcement of requires_approval

tercel — Sat, 16 May 2026 07:08:03 +0000

As AI Agents gain more autonomy, a fundamental fear has taken hold in the enterprise: "What if the Agent does something it shouldn't?"

We’ve all seen the warnings in system prompts: "Please be careful when deleting data." But as every seasoned engineer knows, a prompt is not a security policy. If you want to prevent an AI from accidentally triggering a production deployment or wiping a database, you need a hard, runtime "Kill Switch."

In the apcore protocol, we call this the Approval Gate. In this sixteenth article, we explore how the requires_approval annotation brings "Human-in-the-Loop" (HITL) directly into the heart of the execution pipeline.

Why Autonomy Needs a Brake Pedal

Autonomous Agents are designed to loop: they plan, execute, observe, and repeat. The problem arises during the "Execute" phase. If an Agent decides that the best way to "optimize disk space" is to delete your var/log directory, it will try to do so instantly.

Traditional systems try to solve this with prompt engineering or post-execution auditing. Both are too slow.

At apcore, we implement HITL at Step 5 of our 11-step pipeline. Before the validation runs, and long before your code is executed, the Executor checks for the "Approval" flag.

The `requires_approval` Annotation

Marking a module as "High Stakes" is a single-line operation in apcore:

@module(id="ops.deploy", description="Deploy to production.")
@annotations(requires_approval=True, destructive=True)
def deploy(env: str):
    # Logic...

When this module is invoked, the apcore Executor doesn't run the code. Instead, it halts and triggers an ApprovalHandler.

Pluggable Approval Handlers

The beauty of apcore is that the "Human" doesn't have to be in any specific UI. Because apcore is a protocol, the approval request is projected onto whichever Surface the caller is using:

1. The CLI Surface

If you are running a module via apcore-cli, the terminal will pause and ask:
Module 'ops.deploy' requires approval. Proceed? [y/N]

2. The MCP Surface

If Claude is calling your tool via MCP, apcore-mcp uses the protocol's Elicitation feature. A confirmation dialog appears directly in the Claude or Cursor interface, allowing the user to click "Approve" before the AI continues.

3. The Agent-to-Agent (A2A) Surface

In an A2A workflow, the "Provider Agent" sends an input-required status back to the "Consumer Agent." The Consumer Agent then knows it must pause its task and ask its own human user for permission.

Bypassing Approval: The Trusted Context

There are scenarios where you want to bypass the gate—for example, during automated CI/CD runs or when a highly trusted system administrator is using the CLI.

apcore allows this via the Trusted Context:

CLI: The -y or --yes flag tells the handler to auto-approve.
Identity: You can configure your registry to auto-approve calls from specific identity.types (e.g., "system") while requiring them for "user" or "agent".

Conclusion: Bridging Fear and Autonomy

The path to production AI is not about making models "smarter"—it's about making our infrastructure safer. By enforcing "Human-in-the-Loop" at the protocol level, apcore gives enterprises the confidence to deploy autonomous Agents, knowing that the "Brake Pedal" is always under human control.

Next, we wrap up Volume II with "Observability 2.0: Tracing AI 'Thought Chains' with OpenTelemetry."

This is Article #16 of the **Building the AI-Perceivable World* series. Join us in building secure and governed AI architectures.*

GitHub: aiperceivable/apcore

Pattern-Based ACL: Securing the Boundaries of Agentic Autonomy

tercel — Mon, 11 May 2026 12:29:55 +0000

As we move toward a world of autonomous AI Agents, the "Access Control" problem undergoes a fundamental shift. In the traditional web, we worry about a human user accessing another user's data. In the Agentic era, we have a new nightmare: Agent Hallucinations.

Imagine an Agent that, while trying to solve a complex task, "hallucinates" a call to your executor.database.wipe module because it sounded like a good way to "clear the state." Without a robust security layer, the Agent might actually have the permission to do it.

At apcore, we believe that security must be part of the protocol, not a secondary prompt. In this fifteenth article, we explore the Pattern-Based ACL system that secures the boundaries of AI autonomy.

The Failure of Endpoint-Based Security

Traditional API security often relies on a flat list of allowed endpoints for a specific API key. This approach breaks down when you have hundreds of "Skills" (modules) that Agents need to discover and invoke dynamically. Managing a static list for every possible Agent role becomes an administrative nightmare.

apcore takes a different path: Pattern-Based Access Control.

High-Performance Pattern Matching

The apcore ACL (Access Control List) uses a first-match-wins evaluation logic based on caller and target patterns. This allows you to define broad, high-level security policies that scale automatically as you add new modules.

The Power of Namespaces

Because apcore uses Directory-as-ID, your modules are naturally organized into namespaces. You can write rules like:

allow callers=["api.*"] targets=["orchestrator.*"]: Front-facing APIs can only talk to the reasoning layer.
allow callers=["orchestrator.*"] targets=["executor.*"]: The brain can trigger execution.
deny callers=["*"] targets=["admin.sensitive.*"]: Nobody calls admin tools unless explicitly allowed.

Special Identifiers: @external and @system

To make security management easier, the apcore protocol defines two "Magic Callers":

@external: Represents any call coming from outside the registry (e.g., a CLI tool, a Web request, or an MCP client).
@system: Represents internal framework tasks, such as periodic health checks or background cleanup.

By separating these, you can implement a Zero-Trust AI Policy:

# Only allow external callers to see 'common' tools
- callers: ["@external"]
  targets: ["common.*"]
  effect: allow

# Only internal orchestrators can touch the 'executor' namespace
- callers: ["orchestrator.*"]
  targets: ["executor.*"]
  effect: allow

Conditional Rules: Identity & Depth

Sometimes, a simple "Allow/Deny" based on the module ID isn't enough. apcore supports Conditional ACL Rules that look at the current Context:

Role-Based: Match based on the caller's identity.roles (e.g., "finance_admin").
Identity Type: Differentiate between a user, an agent, and a system caller.
Call Depth: Prevent recursive hallucination attacks by stopping any execution chain that exceeds a certain depth (e.g., max_call_depth: 5).

Audit Trails: Prove Your Autonomy

Security without auditability is useless in an enterprise. Every time the apcore ACL system makes a decision, it generates a structured AuditEntry.

This entry includes:

timestamp: Exactly when the check happened.
decision: Allow or Deny.
matched_rule: Which specific line in your YAML policy triggered the decision.
trace_id: Links the security decision to the specific AI "Thought Chain."

This ensures that if an Agent is denied access to a tool, your security team can see exactly why and who was calling.

Conclusion: A Secure Sandbox for Agents

Pattern-Based ACL turns apcore into more than just a library—it turns it into a Secure Runtime for AI. By enforcing boundaries at the protocol level, we allow Agents to be autonomous without being dangerous.

Next, we’ll look at the "Ultimate Safety Valve": Human-in-the-Loop and the runtime enforcement of requires_approval.

This is Article #15 of the **apcore: Building the AI-Perceivable World* series. Join us in building secure AI architectures.*

GitHub: aiperceivable/apcore

Context Object: State Management and Trace Propagation

tercel — Tue, 05 May 2026 02:55:41 +0000

In our previous articles, we explored the 11-step execution pipeline that secures every AI call. At the center of that pipeline sits a silent but essential hero: the Context Object.

If the pipeline is the "Heart" of apcore, the Context is its "Nervous System." It is the object that carries state, identity, and tracing information from the first entry point down to the deepest nested module call. In this fourteenth article, we go deep into how apcore manages the "Short-Term Memory" of an Agentic system.

The Challenge of Statelessness

AI Agents often perform complex, multi-step tasks. An Agent might first call a search module, then a summarize module, and finally a file.write module.

In a traditional stateless architecture, these calls are isolated. The file.write module doesn't know that it was triggered by a specific search result or that it’s part of a high-priority audit task. This lack of context makes debugging impossible and security fragile.

apcore solves this by injecting a reference-shared Context object into every execution.

Anatomy of the apcore Context

The Context class (defined in apcore.context) is a rich container that provides four critical capabilities:

1. W3C-Compatible Tracing (`trace_id`)

Every call chain in apcore is assigned a unique trace_id (a UUID v4 by default).

W3C Compatibility: apcore can ingest TraceParent headers from external systems (like a web gateway), ensuring that your AI's "Thought Chain" is connected to the original user request in your distributed logs.
Trace Propagation: When Module A calls Module B, the trace_id is automatically carried forward.

2. The Audit Trail (`call_chain`)

The Context maintains a call_chain list that grows as the execution moves deeper.

Example: ["api.v1.user", "orchestrator.order", "executor.payment"].
This provides a real-time "Stack Trace" for AI Agents, allowing the system to detect circular calls and enforce recursion limits.

3. Identity & Permissions (`identity`)

The identity property carries the authenticated caller’s details, including their id, type (user/agent/system), and roles. This is the data that the ACL system uses to decide if a call should be allowed.

4. Shared Memory (`data`)

Perhaps the most powerful feature is context.data—a dictionary that is reference-shared across the entire call chain.

Unlike module inputs (which are local), context.data allows modules to pass artifacts "sideways."
Real-world use case: A middleware can calculate a session token once and store it in context.data, making it available to all subsequent modules in that chain without cluttering their input parameters.

Implementation: The Child Context Pattern

How does apcore ensure that the context stays accurate during nested calls? It uses the Child Context Pattern.

When you call another module via context.executor.call(), the system doesn't just pass the parent context. It creates a .child() context:

# Inside Module A
def execute(self, inputs, context):
    # This creates a child context with:
    # 1. Same trace_id
    # 2. Updated caller_id (now Module A)
    # 3. Appended call_chain
    # 4. SHARED data dictionary
    result = context.executor.call("module_b", inputs, context)

This ensures that the caller_id always points to the immediate parent, while the trace_id and data remain consistent across the entire journey.

Conclusion: Turning Isolation into Collaboration

By standardizing state management through the Context Object, apcore turns a collection of isolated functions into a coherent, intelligent workforce. It provides the "Short-Term Memory" that AI Agents need to perform complex, traceable, and secure operations.

Next, we’ll see how this identity data is used to enforce security in "Pattern-Based ACL: Securing the Boundaries of Agentic Autonomy."

This is Article #14 of the **apcore: Building the AI-Perceivable World* series. Identity and State are the foundation of Trust.*

GitHub: aiperceivable/apcore

Behavioral Annotations: Why readonly and destructive guide LLM Planning

tercel — Mon, 04 May 2026 01:07:46 +0000

In our previous article, we discussed how Schemas act as the "Postman" of the apcore ecosystem—ensuring that data is delivered in the correct format. But knowing how to deliver a message isn't enough for an autonomous Agent. The Agent also needs to know the Impact of the delivery.

Imagine an Agent tasked with "fixing a data inconsistency." It finds two modules: common.user.sync and executor.user.reset. Without behavioral context, the Agent might pick the reset module because it sounds more "thorough," not realizing it will delete the entire user profile.

This is why Behavioral Annotations are a core technical pillar of the apcore protocol. In this thirteenth article, we explore how these simple boolean flags act as "Cognitive Stop Signs" for AI planners.

Syntax vs. Semantics

A schema handles the Syntax (Is it a string? Is it required?). Annotations handle the Semantics (Is it safe? Is it permanent?).

By providing this semantic layer, we move from "Code-Calling" to "Skill-Perceiving." The AI Agent no longer treats your modules as black boxes; it perceives their personality.

The 12 apcore Behavioral Annotations

The apcore protocol defines a set of standardized annotations that provide the semantic "Personality" for your code. These are grouped into Safety, Execution, and Governance:

Safety & Impact

readonly: No side effects. Safe for discovery and infinite retries.
destructive: Data will be permanently modified or deleted.
idempotent: Multiple calls with same input have same effect as one.
pure: Output depends only on input; no external state dependency.

Execution & Performance

streaming: The module returns a stream of events/chunks rather than a single block.
cacheable: Results can be stored for future use.
cache_ttl: How long (in seconds) the result remains valid.
paginated: The result is part of a series; requires a cursor/token to continue.

Governance & Security

requires_approval: Pauses execution for a human "Yes" (HITL).
open_world: Interacts with non-deterministic external systems (e.g., Web, Email).
internal: Hidden from standard discovery; used for system-to-system calls.
extra: A catch-all map for surface-specific or custom behavioral hints.

Guiding the Agent's Brain

How does an LLM actually use these flags? It’s all about the Planning Phase.

When a sophisticated Agent (like those powered by Claude 3.5 or GPT-4o) receives a list of tools, it builds a "Plan of Action."

If it sees a module marked as destructive: true, the model's internal safety alignment often triggers a "Caution" state.
It might decide to check for a "Dry Run" flag first.
Or, it might generate a response to the user: "I have found a way to fix this, but it requires a destructive database operation. Do you want me to proceed?"

Without these annotations, the Agent is "blind." It executes the plan first and discovers the consequences later—which is usually too late.

Real-World Case: `apexe`

The power of automated annotations is a highlight of apexe, our tool for wrapping existing CLIs. When you run apexe scan git, it doesn't just extract the parameters. It uses pattern matching to classify the commands:

git status and git log are automatically marked as readonly: true.
git push --force and git reset --hard are marked as destructive: true.

By simply scanning your help text, apexe creates a "Safe Workspace" where an AI Agent can browse your repository without accidentally blowing up your production branch.

Conclusion: Professional Skills, Not Just Functions

Engineering for AI means engineering for Cognitive Safety. By using apcore Behavioral Annotations, you turn your raw functions into "Professional Skills." You give the AI the wisdom it needs to plan responsibly, reducing token waste and preventing Agentic disasters.

Next, we’ll dive into the AI’s "Short-Term Memory": The Context Object and how it manages traces and state across complex module chains.

This is Article #13 of the **apcore: Building the AI-Perceivable World* series. Safety is a protocol-level primitive.*

GitHub: aiperceivable/apcore

Strict Schema Enforcement: The Bedrock of AI Reliability

tercel — Fri, 01 May 2026 11:21:24 +0000

In the early days of AI tool-calling, we relied on a wing and a prayer. We gave an LLM a docstring and hoped it would guess the right types. If the Agent sent a string instead of a UUID, or a float instead of an integer, the system would crash, returning a generic 500 error that left the Agent stuck in an infinite retry loop.

This is Parameter Hallucination, and it is the single biggest obstacle to building production-grade AI systems.

At apcore, we solve this by making Strict Schema Enforcement a protocol-level requirement. In this twelfth article of our series, we dive into why data contracts are the only way to build a reliable Cognitive Interface.

Why JSON Schema Draft 2020-12?

When we designed apcore, we didn't want to invent a new schema language. We chose JSON Schema Draft 2020-12.

Why? Because it is the "Universal Vocabulary" of the modern web. It is language-agnostic, widely supported, and incredibly expressive. By standardizing on this draft, we ensure:

Cross-Language Consistency: A schema defined in your Python backend is validated with the exact same logic in your Rust microservice.
Rich Polymorphism: We can use oneOf and anyOf to define complex inputs that an LLM can actually reason about.
Self-Contained Definitions: With $ref resolution, apcore ensures that the LLM always receives a single, dereferenced schema, removing the need for the model to "fetch" external definitions.

Mandatory Perception

In apcore, a module cannot exist without an input_schema. This isn't a suggestion; it’s an enforcement in the Registry.

By forcing developers to define the input contract upfront, we create a Safe Zone for the AI Agent. The Agent no longer has to "guess" if a field is required or what its regex pattern is. It "perceives" the contract directly from the module metadata.

The "Strict" Mode

apcore encourages the use of additionalProperties: false. This tells the LLM: "Do not hallucinate extra parameters. Only send exactly what is defined here." This small architectural choice significantly reduces token noise and increases the success rate of complex tool calls.

The Execution Pipeline: Step 6

The power of strict schemas is best seen in Step 6 of the apcore Execution Pipeline: Input Validation.

Before your business logic ever touches the data, the apcore Executor runs a full schema validation. If the LLM makes a mistake—sending a string instead of a number—the Executor halts execution immediately.

But here is the clever part: instead of a stack trace, it returns a Structured Validation Error.

{
  "code": "SCHEMA_VALIDATION_ERROR",
  "message": "Input validation failed",
  "details": {"field": "user_id", "reason": "not a valid UUID"},
  "ai_guidance": "The user_id must be a UUID format. Please re-check the user record and try again."
}

This error informs the Agent exactly what went wrong, allowing it to self-correct and retry without human intervention.

Conclusion: Engineering the Contract

If you want reliable AI Agents, you must stop "Prompting" your tools and start Engineering your Contracts. Strict schema enforcement is not about adding friction; it’s about providing the semantic clarity that AI needs to act autonomously and safely.

Next, we’ll move from syntax to semantics: Behavioral Annotations. We’ll look at how 'readonly' and 'destructive' guide the LLM's planning process.

This is Article #12 of the **apcore: Building the AI-Perceivable World* series. Reliability is a design choice.*

GitHub: aiperceivable/apcore

The 11-Step Execution Pipeline: A Secured Journey for Every Call

tercel — Thu, 30 Apr 2026 08:28:08 +0000

When an AI Agent calls a tool, we often think of it as a simple "request-response" event. But in the apcore world, every call is a mission-critical journey. Whether you are invoking a Python module or a Rust microservice, that call passes through a rigorous, 11-step Execution Pipeline.

This pipeline is the "Heart" of the apcore engine. It ensures that every interaction is validated, authorized, and perfectly traceable. In this eleventh article, we’re going to open the hood and see exactly how apcore ensures reliability at scale.

The apcore Execution Pipeline

Every call through the Executor.call() method follows this deterministic path:

Context Processing: Create or update the Context. Generate a trace_id (if one doesn't exist) and update the caller_id and call_chain.
Safety Checks: Verify the maximum call depth (default 8) to prevent circular calls from crashing the system.
Module Lookup: Find the target module in the Registry using its Canonical ID.
ACL Check: Perform the first-match-wins Access Control List check. Does the caller have permission to invoke the target?
Approval Gate: Check if the module is marked as requires_approval. If so, pause execution and wait for a human or automated response.
Input Validation: Validate the incoming dict against the module's input_schema (JSON Schema Draft 2020-12).
Middleware: before(): Execute all registered middleware's before() hooks in sequence (e.g., logging, metrics, caching).
Module Execution: The actual module.execute(inputs, context) call. This is where your business logic runs.
Output Validation: Validate the returned result against the output_schema.
Middleware: after(): Execute all middleware's after() hooks in reverse order.
Return Result: Hand the validated and enriched result back to the caller.

Why 11 Steps? (The Real-World Case of `apflow`)

You might wonder: "Isn't 11 steps overkill?"

The answer lies in products like apflow, our distributed task orchestration framework. In a cluster environment, where tasks are moving between nodes, you cannot afford "fuzzy" execution.

Traceability at Scale

By enforcing Step 1 (Context Processing), apflow ensures that a task triggered by a user's web request keeps the same trace_id even as it moves from the Leader node to a remote Worker node. This is the only way to debug a "hallucinating" Agent in a distributed environment.

Governance in Autonomy

Step 5 (Approval Gate) is critical for apflow's A2A (Agent-to-Agent) support. If an "Analyst Agent" wants to call a "Payment Agent," apflow uses this step to pause the workflow and wait for a human "Manager" to click "Approve" in the dashboard. Without this step, the system would lack a "Safety Valve."

Security Without Borders

Step 4 (ACL Check) allows apflow to enforce "Role-Based" security. A RestExecutor node might only be allowed to call common.* modules, while a SystemInfoExecutor node might have broader access.

Technical Rigor: Middleware & Error Guidance

The pipeline isn't just a set of checks; it’s an extension point. In Step 7 and 10, you can inject custom logic via Middleware.

And if any step fails? apcore doesn't just throw a traceback. It provides Self-Healing Guidance. If validation fails at Step 6, the pipeline returns an error with ai_guidance, telling the Agent exactly how to fix the input and retry.

Conclusion: The Backbone of Trust

Reliability in AI systems is not an accident; it is a structural property of the execution pipeline. By enforcing an 11-step journey, apcore ensures that every AI call is as secure and predictable as a high-performance database transaction.

Next, we’ll dive into the technical details of Article #12: Strict Schema Enforcement: The Bedrock of AI Reliability.

This is Article #11 of the **apcore: Building the AI-Perceivable World* series. Join us as we build the engine of the Agentic era.*

GitHub: aiperceivable/apcore

The Execution Pipeline: A Secured Journey for Every Call

tercel — Thu, 23 Apr 2026 23:42:40 +0000

The apcore Execution Pipeline

Every call through the Executor.call() method follows this deterministic path:

Context Processing: Create or update the Context. Generate a trace_id (if one doesn't exist) and update the caller_id and call_chain.
Safety Checks: Verify the maximum call depth (default 8) to prevent circular calls from crashing the system.
Module Lookup: Find the target module in the Registry using its Canonical ID.
ACL Check: Perform the first-match-wins Access Control List check. Does the caller have permission to invoke the target?
Approval Gate: Check if the module is marked as requires_approval. If so, pause execution and wait for a human or automated response.
Input Validation: Validate the incoming dict against the module's input_schema (JSON Schema Draft 2020-12).
Middleware: before(): Execute all registered middleware's before() hooks in sequence (e.g., logging, metrics, caching).
Module Execution: The actual module.execute(inputs, context) call. This is where your business logic runs.
Output Validation: Validate the returned result against the output_schema.
Middleware: after(): Execute all middleware's after() hooks in reverse order.
Return Result: Hand the validated and enriched result back to the caller.

Why 11 Steps? (The Real-World Case of `apflow`)

You might wonder: "Isn't 11 steps overkill?"

The answer lies in products like apflow, our distributed task orchestration framework. In a cluster environment, where tasks are moving between nodes, you cannot afford "fuzzy" execution.

Traceability at Scale

Governance in Autonomy

Security Without Borders

Technical Rigor: Middleware & Error Guidance

The pipeline isn't just a set of checks; it’s an extension point. In Step 7 and 10, you can inject custom logic via Middleware.

Conclusion: The Backbone of Trust

Next, we’ll dive into the technical details of Article #12: Strict Schema Enforcement: The Bedrock of AI Reliability.

This is Article #11 of the **apcore: Building the AI-Perceivable World* series. Join us as we build the engine of the Agentic era.*

GitHub: aiperceivable/apcore

Directory-as-ID: Scaling Module Discovery Without Configuration

tercel — Thu, 23 Apr 2026 10:42:20 +0000

In the previous volume, we explored the vision of an "AI-Perceivable" world. Now, it’s time to go under the hood. The first technical pillar of the apcore protocol is a deceptively simple idea: Directory-as-ID.

In a traditional microservices or modular architecture, you often have a central registry, a massive YAML configuration file, or a complex dependency injection container. As your system grows from 10 modules to 1,000, this central "phonebook" becomes a bottleneck. It’s the source of merge conflicts, naming collisions, and "Scaling Rot."

apcore solves this by making the file system the source of truth. In this tenth article, we’ll look at the algorithm behind Directory-as-ID and why it’s essential for scaling AI-ready systems.

The Algorithm: From Path to Canonical ID

The principle is straightforward: The relative path of a module file is its unique identity.

If you have a module root directory (e.g., extensions/), apcore scans the files and applies a deterministic mapping:

Remove the Root: extensions/executor/email/send.py -> executor/email/send.py
Remove Extension: executor/email/send.py -> executor/email/send
Normalize Separators: executor/email/send -> executor.email.send (The Canonical ID)

Why this matters for AI:

AI Agents are highly sensitive to names. By using a hierarchical, directory-based naming convention, you naturally create Namespaces. An Agent can quickly differentiate between executor.user.delete and admin.user.delete because the hierarchy provides the context.

Case Study: Zero-Config in `apexe`

The power of Directory-as-ID is best seen in real-world products like apexe.

apexe: AI-fying the CLI Universe

apexe is a tool that scans existing CLIs (like git or docker) and wraps them into apcore modules. When you run apexe scan git, it generates a hierarchy of modules under your ~/.apexe/modules/ directory.

git commit becomes cli.git.commit
git push becomes cli.git.push

Because of Directory-as-ID, apexe doesn't need to manage a database of IDs. It simply writes the files to the right folders, and the apcore Registry "perceives" the entire CLI command tree instantly. This enables Dynamic Skill Discovery: if you install a new CLI tool and scan it, your Agent can perceive it immediately without a single server restart.

Technical Rigor: Handling Multi-Language Drift

A core challenge of a language-agnostic standard is that different languages have different naming conventions. Python likes snake_case, while TypeScript prefers camelCase.

The apcore protocol defines strict ID Normalization Rules:

Normalization: All IDs are converted to a "Canonical" form (lowercase, snake_case) for the Registry.
Language Mapping: Each SDK (Python, TS, Rust) handles the translation between the Canonical ID and the local file name (e.g., SendEmail.ts maps to send_email).

This ensures that even in a polyglot enterprise, the AI Agent sees a single, consistent address space.

Conclusion: Scale is a Design Constraint

Directory-as-ID is more than a convenience; it’s a design constraint for the Agentic Era. It enables Zero-Config Discovery, eliminates registry bottlenecks, and provides a natural namespace for AI perception.

In the next article, we’ll dive into the heart of the engine: The 11-Step Execution Pipeline.

This is Article #10 of the **apcore: Building the AI-Perceivable World* series. Join us as we go deep into the protocol.*

GitHub: aiperceivable/apcore

DEV Community: tercel

Type-Safe Agents: Leveraging apcore-js in TypeScript

The Goal: Cross-Language Parity

Defining Type-Safe Schemas

Building the Module

Automated Discovery & Mapping

Trace Propagation in the Node Mesh

Conclusion: Reliability at Compile Time

Pythonic AI: Mastering the apcore-python SDK

Defining Modules: The Two Styles

1. The Decorator Style (Fast & Functional)

2. The Class Style (Structured & Extensible)

Pydantic Integration: The Secret Weapon

Initializing the Core

Execution & Async Support

Conclusion: Built for Developers, Ready for AI

apcore-toolkit: The Utility Backbone for Module Developers

Don't Reinvent the Scanner

Convention Module Discovery (§5.14)

The Display Overlay System (§5.13)

AIEnhancer: The Lazy Developer’s Best Friend

Conclusion: Velocity Through Standardization

Observability 2.0: Tracing AI "Thought Chains" with OpenTelemetry

The Concept of the "Thought Span"

Distributed Tracing: From LLM to DB

Metrics for the Agentic Era

Implementation: One-Line Observability

Conclusion: Engineering Transparency

Summary of Volume II: The Engine

Human-in-the-Loop: The Runtime Enforcement of requires_approval

Why Autonomy Needs a Brake Pedal

The requires_approval Annotation

Pluggable Approval Handlers

1. The CLI Surface

2. The MCP Surface

3. The Agent-to-Agent (A2A) Surface

Bypassing Approval: The Trusted Context

Conclusion: Bridging Fear and Autonomy

Pattern-Based ACL: Securing the Boundaries of Agentic Autonomy

The Failure of Endpoint-Based Security

High-Performance Pattern Matching

The Power of Namespaces

Special Identifiers: @external and @system

Conditional Rules: Identity & Depth

Audit Trails: Prove Your Autonomy

Conclusion: A Secure Sandbox for Agents

Context Object: State Management and Trace Propagation

The Challenge of Statelessness

Anatomy of the apcore Context

1. W3C-Compatible Tracing (trace_id)

2. The Audit Trail (call_chain)

3. Identity & Permissions (identity)

4. Shared Memory (data)

Implementation: The Child Context Pattern

Conclusion: Turning Isolation into Collaboration

Behavioral Annotations: Why readonly and destructive guide LLM Planning

Syntax vs. Semantics

The 12 apcore Behavioral Annotations

Safety & Impact

Execution & Performance

Governance & Security

Guiding the Agent's Brain

Real-World Case: apexe

Conclusion: Professional Skills, Not Just Functions

Strict Schema Enforcement: The Bedrock of AI Reliability

Why JSON Schema Draft 2020-12?

Mandatory Perception

The "Strict" Mode

The Execution Pipeline: Step 6

Conclusion: Engineering the Contract

The 11-Step Execution Pipeline: A Secured Journey for Every Call

The apcore Execution Pipeline

Why 11 Steps? (The Real-World Case of apflow)

Traceability at Scale

Governance in Autonomy

Security Without Borders

Technical Rigor: Middleware & Error Guidance

Conclusion: The Backbone of Trust

The Execution Pipeline: A Secured Journey for Every Call

The apcore Execution Pipeline

The `requires_approval` Annotation

1. W3C-Compatible Tracing (`trace_id`)

2. The Audit Trail (`call_chain`)

3. Identity & Permissions (`identity`)

4. Shared Memory (`data`)

Real-World Case: `apexe`

Why 11 Steps? (The Real-World Case of `apflow`)

Why 11 Steps? (The Real-World Case of `apflow`)

Case Study: Zero-Config in `apexe`