DEV Community: tercel

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

Building for the Next 10 Years: The Design Principles of apcore

tercel — Wed, 22 Apr 2026 12:40:38 +0000

We’ve reached the end of Volume I of our series. We’ve explored the problems with "Vibe-based" engineering, the rise of the Cognitive Interface, and the immediate power of the apcore Adapter ecosystem.

But as any experienced engineer knows, a standard is only as good as its foundational principles. In the fast-moving world of AI, where frameworks disappear every six months, how do we build something that will still be relevant in 2030?

In this ninth and final post of our Manifesto, we outline the five design principles that guide the apcore standard.

Principle #1: Schema-Enforced Everything

In the early days of the web, "Postel’s Law" (be conservative in what you send, liberal in what you accept) was the rule. For AI Agents, we believe the opposite is true: Be strict in everything.

Reliability in an Agentic system is impossible without strict contracts. In apcore, a module without a schema is not a module—it is a bug. By enforcing JSON Schema at the protocol level, we ensure that the AI Agent and the code always speak a deterministic, validated language.

Principle #2: Directory-as-ID (Zero-Config DX)

Developer Experience (DX) is not a luxury; it is a security feature. When developers have to manually register every tool in a central configuration file, "Scaling Rot" sets in. People forget to update the config, IDs conflict, and the system becomes a mess.

apcore uses the file system as the source of truth. The path extensions/executor/email/send.py automatically becomes the Canonical ID executor.email.send. This makes discovery natural, scalable, and impossible to "forget."

Principle #3: Progressive Disclosure of Metadata

AI Agents have limited context windows and expensive tokens. You cannot dump your entire 5,000-page API manual into every prompt.

apcore is designed for Progressive Disclosure. The Agent scans short descriptions for discovery, checks annotations for planning, and only reads the full documentation when it’s ready to execute. This "just-in-time" metadata delivery is essential for large-scale Agentic systems.

Principle #4: Language-Agnostic & Protocol-First

An AI-Perceivable module should not be a "Python feature." It is a structural property of the software. Whether your backend is in Rust, TypeScript, or Go, it must project the same "Cognitive Interface."

By prioritizing the Protocol Specification over any individual SDK, we ensure that an enterprise can build a heterogeneous, multi-language workforce that speaks a single semantic language.

Principle #5: Governance as a First-Class Citizen

Safety is not an "add-on" you prompt-engineer at the end. It must be baked into the lifecycle. Access Control Lists (ACL), Human-in-the-Loop (Approval Gates), and Structured Error Guidance are core primitives of the apcore protocol.

We don't "ask" the AI to be safe; we enforce safety at the runtime level.

Summary of Volume I: The Manifesto

We started this series with a goal: to move from "Prompting Tools" to "Engineering Modules." Over these nine articles, we’ve laid out the vision for an AI-Perceivable World.

We’ve shown that:

Reliability comes from Enforcement, not better prompts.
The Cognitive Interface is the next layer of the stack.
The Adapter Pattern allows one module to serve MCP, A2A, CLI, and Web.

What’s Next: Volume II — The Core Protocol Deep Dive

Now that we’ve established the Why, it’s time to look at the How. In our next volume, we will go "Under the Hood." We’ll look at the actual algorithms behind Directory-as-ID, the 11-step Execution Pipeline, and the math of pattern-based ACL.

Stay tuned. The deep dive begins.

This is Article #9 of the **apcore: Building the AI-Perceivable World* series. Join us in building the architecture for the next decade.*

GitHub: aiperceivable/apcore

The Death of "String-Based" Descriptions in AI Integration

tercel — Mon, 20 Apr 2026 11:26:32 +0000

In the early days of building AI tools, we all followed the same pattern:

Define a function.
Write a clever docstring like: "This tool is very fast and deletes users securely."
Pass it to the LLM.
Pray it understands what "very fast" and "securely" means.

As we move into 2026, it’s time to admit the truth: Free-form string descriptions are the #1 reason AI Agents fail.

When you rely on "Vibes" (Prompt Engineering) to define your tools, you are essentially asking the AI to guess your intent. In this eighth post of our apcore series, we explain why we’re moving beyond "String-Based" descriptions toward a world of Structured Metadata.

The Illusion of Clarity

LLMs are semantic engines. They look for patterns in language. If you have two tools in your system—remove_user and delete_account—an LLM might treat them as synonyms. Even if you add a sentence explaining the difference, the model’s internal weights might still bias it toward one over the other based on its training data.

This is what we call "Description Drift." As your engineering team grows, different developers write descriptions in different styles. One uses emojis, another uses technical jargon, and a third uses vague adjectives.

To the AI, your "Cognitive Interface" starts to look like a messy, unorganized library. The result? The Agent calls the wrong tool at the wrong time, leading to security breaches or data loss.

apcore’s Dual-Layered Metadata

At apcore, we’ve replaced the single-string description with a Dual-Layered Metadata Model. We borrow this concept from the way humans learn complex skills: we scan the table of contents first, and only read the detailed manual when we’re ready to act.

1. The Discovery Layer (`description`)

A mandatory, short string (max 200 characters). This is optimized for the AI's "Search" phase. It tells the AI: "This tool exists, and this is its high-level purpose."

Purpose: Discovery and RAG (Retrieval-Augmented Generation).

2. The Cognitive Layer (`documentation`)

A long-form, Markdown-supported field (up to 5000 characters). This is the "Manual." It contains detailed use cases, constraints, business logic, and "What NOT to do" warnings.

Purpose: Planning and Precision. The AI only "reads" this once it has tentatively selected the tool for the task.

class PaymentModule(Module):
    # Discovery: Fast, cheap to read
    description = "Process credit card payments via Stripe."

    # Cognition: Detailed, read only when needed
    documentation = """
    ## Usage Rules
    - Only use for 'USD' transactions. For others, use `executor.fx.payment`.
    - Maximum single charge: $5,000.
    - Requires `stripe_api_key` in the system configuration.

    ## Common Pitfalls
    - Do NOT call this twice for the same order_id; it is not idempotent by default.
    """

Schema-Enforced Descriptions

In apcore, having a description and a schema isn't a "best practice"—it's an Enforcement. You literally cannot register a module in an apcore Registry without providing these metadata fields.

This ensures that your system is Self-Documenting for AI. Every time a new developer adds a module, they are forced to define its "Cognitive Interface." This prevents "invisible tools" from cluttering your system and ensures that the AI always has the information it needs to succeed.

Moving Beyond "Adjective Engineering"

Instead of telling the AI that a tool is "safe," we use Behavioral Annotations. We mark it as destructive=False and requires_approval=True. These aren't just strings; they are structured primitives that the apcore Executor uses to govern the call.

By moving from "Strings" to "Structures," we reduce the cognitive load on the LLM. It no longer has to "guess" the intent of your code; it simply "perceives" the contract.

In our next article, we wrap up Volume I by looking at the "Design Principles of apcore" that will guide us for the next 10 years.

This is Article #8 of the **apcore: Building the AI-Perceivable World* series. Engineering metadata is the foundation of reliable AI.*

GitHub: aiperceivable/apcore

Standardizing "Intelligence": The 3-Layer Metadata Philosophy

tercel — Sat, 18 Apr 2026 00:12:45 +0000

In our previous posts, we’ve discussed why AI Agents fail when they rely on "vibes" and why they need a "Cognitive Interface." But what does "Intelligence" actually look like at the code level?

If you ask ten developers how to describe a tool to an AI, you’ll get ten different answers. Some will focus on technical types, others on flowery descriptions, and some on security.

At apcore, we’ve standardized this "Intelligence" into a 3-Layer Metadata Stack. By separating technical syntax from behavioral governance and tactical wisdom, we ensure that an AI Agent perceives your module with 360-degree clarity.

The apcore 3-Layer Stack

We visualize the "Intelligence" of a module as a stack that moves from Required to Tactical:

Layer 1: The Core (Syntax & Discovery)

This is the "bare minimum" for a module to exist in the apcore ecosystem.

input_schema: Exactly what the AI must send.
output_schema: Exactly what the AI will receive.
description: A short "blurb" for the AI's search engine.

The Goal: Precision. If the AI doesn't get the syntax right, nothing else matters. By enforcing JSON Schema Draft 2020-12, we provide a universal language that any LLM can understand.

Layer 2: The Annotations (Governance & Behavior)

Once the AI understands how to call the module, it needs to understand should it call it. This layer defines the "Personality" and "Safety Profile" of your code.

readonly: Is it safe to call this multiple times for information?
destructive: Will this delete or overwrite data?
requires_approval: Does a human need to click "Yes" before this runs?
idempotent: Can the AI safely retry if the connection drops?

The Goal: Governance. We move security and policy from the prompt into the protocol.

Layer 3: The Extensions (Tactical Wisdom)

This is where the "Senior Engineer" lives. This layer provides the subtle context that prevents the AI from making logical mistakes.

x-when-to-use: Positive guidance for the Agent's planner.
x-when-not-to-use: Negative guidance to prevent common misfires.
x-common-mistakes: Pitfalls discovered during development.

The Goal: Tactical Wisdom. We inject human experience directly into the module's metadata.

Why a "Stacked" Approach?

Traditional AI tools often dump all of this into a single description string. This creates Cognitive Overload. The LLM has to parse the syntax, the security rules, and the usage tips all at once.

In apcore, we use Progressive Disclosure:

The Agent's "Discovery" phase only sees Layer 1.
The Agent's "Planning" phase loads Layer 2 to check for safety and retries.
The Agent's "Execution" phase loads Layer 3 to ensure it doesn't fall into known traps.

By stacking the metadata, we reduce token usage and significantly increase the reliability of the Agent's reasoning.

A Complete "Intelligent" Module

Here is what a fully-realized apcore module looks like:

class SensitiveTransferModule(Module):
    # Layer 1: Core
    input_schema = TransferInput
    description = "Transfer funds to an external IBAN."

    # Layer 2: Annotations
    annotations = ModuleAnnotations(
        destructive=True,
        requires_approval=True, # Safety gate
        idempotent=True
    )

    # Layer 3: Extensions (AI Wisdom)
    metadata = {
        "x-when-not-to-use": "Do not use for internal account transfers.",
        "x-common-mistakes": "Ensure the IBAN includes the country code.",
        "x-preconditions": "User must be MFA authenticated."
    }

Conclusion: Engineering Intelligence

"Intelligence" in the Agentic era is not a magic property of the model; it is an Engineering Standard of the module. When you build with the apcore 3-Layer Philosophy, you aren't just writing code—you are engineering a "Skill" that any AI can perceive and use with professional precision.

In our next article, we’ll tackle the root cause of AI hallucinations: "The Death of 'String-Based' Descriptions in AI Integration."

This is Article #7 of the **apcore: Building the AI-Perceivable World* series. Join us in standardizing the future of AI interaction.*

GitHub: aiperceivable/apcore

"Beyond the Brain: Exposing AI Modules to REST, gRPC, and GraphQL"

tercel — Fri, 17 Apr 2026 12:03:51 +0000

We’ve seen how apcore modules can be called by Claude via MCP, by humans via the CLI, and by other Agents via A2A. But in the enterprise, there is a massive world of legacy systems, mobile apps, and web frontends that still speak the traditional languages of the web: REST, gRPC, and GraphQL.

The challenge for most developers is "Interface Duplication." You build a tool for your AI Agent, and then you have to rewrite the same validation, security, and documentation logic to expose it as a REST API for your React frontend.

In this sixth article of our series, we look at how apcore turns your AI-Perceivable modules into universal web services using framework adapters like fastapi-apcore and flask-apcore.

The "Surface" Philosophy

In apcore, we treat different protocols as Surfaces. A surface is a thin layer that projects the internal logic of an apcore module into a specific network format.

By using framework-specific integrations, you can project your entire module Registry onto the web with zero duplication.

1. RESTful Auto-Mapping

With adapters like flask-apcore, your module executor.user.get_profile automatically becomes a REST endpoint:
GET /api/v1/executor/user/get_profile

The input_schema is used to validate the incoming JSON body or query parameters, and the output_schema ensures the response is consistent. This is done at the middleware level, ensuring your business logic stays "pure."

2. gRPC for High-Performance

For internal microservices, apcore integrations can generate Protobuf definitions on the fly, allowing your legacy Java or Go services to call your AI-Perceivable Python modules with binary efficiency.

Why Web Exposure is Better with apcore

When you use an apcore framework adapter, you aren't just getting an auto-generated router. You are getting the entire apcore Execution Pipeline:

Unified ACL: The same pattern-based access control that protects your modules from AI hallucinations also protects them from unauthorized web requests.
Trace Propagation: If a web request triggers an apcore module, the adapter captures the trace-id (or generates a new one) and propagates it through any internal module-to-module calls.
Schema-Driven Documentation: Your apcore description and documentation fields can be automatically exported as Swagger/OpenAPI docs for your frontend team.

Code Showcase: The Universal Backend

Imagine you are building a simple "Weather Module" using FastAPI. Here is how you expose it to the world:

# The AI-Perceivable Module
@module(id="common.weather.get", description="Get current weather for a city.")
def get_weather(city: str) -> dict:
    return {"temp": 22, "condition": "Sunny"}

# The Web Surface (FastAPI)
from fastapi import FastAPI
from fastapi_apcore import register_routes

app = FastAPI()
register_routes(app, registry) # All modules now have REST endpoints automatically

One definition. Your AI Agent calls it. Your CLI tool calls it. Your React app calls it. Zero duplication.

Conclusion: The Bridge to the Future

The "Agentic Era" doesn't mean we throw away the web. It means we upgrade the web to be AI-Perceivable. Framework adapters ensure that your AI investment is also a "Web 2.0" investment, creating a bridge between your legacy infrastructure and your autonomous future.

Now that we’ve seen the power of the apcore Adapter Ecosystem, it’s time to go under the hood. In the next article, we’ll dive into the 3-Layer Metadata Philosophy that makes all of this possible.

This is Article #6 of the **apcore: Building the AI-Perceivable World* series. Build once, serve everywhere.*

GitHub: aiperceivable/apcore

DEV Community: tercel

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

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

Directory-as-ID: Scaling Module Discovery Without Configuration

The Algorithm: From Path to Canonical ID

Why this matters for AI:

Case Study: Zero-Config in apexe

apexe: AI-fying the CLI Universe

Technical Rigor: Handling Multi-Language Drift

Conclusion: Scale is a Design Constraint

Building for the Next 10 Years: The Design Principles of apcore

Principle #1: Schema-Enforced Everything

Principle #2: Directory-as-ID (Zero-Config DX)

Principle #3: Progressive Disclosure of Metadata

Principle #4: Language-Agnostic & Protocol-First

Principle #5: Governance as a First-Class Citizen

Summary of Volume I: The Manifesto

What’s Next: Volume II — The Core Protocol Deep Dive

The Death of "String-Based" Descriptions in AI Integration

The Illusion of Clarity

apcore’s Dual-Layered Metadata

1. The Discovery Layer (description)

2. The Cognitive Layer (documentation)

Schema-Enforced Descriptions

Moving Beyond "Adjective Engineering"

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`

1. The Discovery Layer (`description`)

2. The Cognitive Layer (`documentation`)