apcore — AI-Perceivable Core

AI-Perceivable: When modules, interfaces, and tools are clearly perceived by AI, the model can understand their structure and purpose, and therefore know exactly how to invoke, orchestrate, and act on them. From perception → cognition → execution.

Build once, invoke by Code or AI.

A schema-enforced module standard for the AI-Perceivable era.

apcore is an AI-Perceivable module standard that makes every interface naturally perceivable and understandable by AI through enforced Schema definitions and behavioral annotations.

apcore is a protocol specification. Language implementations are maintained in separate repositories:

| SDK | Language | Install | Repository | |-----|----------|---------|------------| | apcore | Python | pip install apcore | github.com/aiperceivable/apcore-python | | apcore-js | TypeScript | npm install apcore-js | github.com/aiperceivable/apcore-typescript | | apcore | Rust | cargo add apcore | github.com/aiperceivable/apcore-rust |

What is apcore?
- The Concept: Cognitive Interface
- Why Not Just Use Existing MCP Solutions?
Why AI-Perceivable?
- The AI Collaboration Lifecycle
Core Principles
Architecture Overview
Quick Start
Module Development
- Two Integration Paths
- Class-based Modules
- @module Decorator
- module() Function Call
- External Binding (Zero Code Modification)
Schema System
- Three-Layer Metadata Design
- Module Annotations
- LLM Extension Fields
Context Object
ACL Access Control
Middleware
Configuration
Observability
Error Handling & AI Guidance
Cross-Language Support
Relationship with Other Tools
Implementations
Ecosystem
Documentation Index
Contributing
License

What is apcore?

apcore is an AI-Perceivable module standard that makes every module naturally perceivable and understandable by AI through enforced Schema definitions.

┌─────────────────────────────────────────────────────────────┐
│                apcore — AI-Perceivable Core                 │
│                                                             │
│  AI-Perceivable module standard + Enforced Schema          │
│  - Directory as ID (zero-config module discovery)          │
│  - Schema-driven (input/output mandatory)                  │
│  - ACL / Observability / Middleware                        │
└─────────────────────────────────────────────────────────────┘
                            ↓ Modules callable by
      ┌──────────┬──────────┬──────────┬──────────┐
      │          │          │          │          │
  Legacy Code  AI/LLM    HTTP API    CLI Tool   MCP Server
   (import)  (understands) (REST)    (terminal)  (Claude)

Not just an AI framework, but a module standard that is naturally AI-Perceivable.

The Concept: Cognitive Interface

Traditional software provides UI for humans and API for programs. apcore provides the Cognitive Interface for AI Agents:

Intent-Oriented: AI thinks in "What to do" (Intents), not "Which endpoint to call".
Strict Contracts: Mandatory schemas ensure AI uses your tools correctly every time.
Behavioral Personality: Annotations like readonly and destructive guide Agent decisions.

Why Not Just Use Existing MCP Solutions?

Today, many projects build their own MCP servers independently — Stripe has one, TipTap has one, NestJS has one. Each uses different interfaces, different standards, and none provides a programmable SDK. The result is a fragmented ecosystem where developers must learn a new approach for every integration.

apcore takes a different path: SDK-first, standard-unified.

| | Fragmented MCP Solutions | apcore | |---|---|---| | Programmable SDK | No — only MCP servers | Yes — apcore-python, apcore-typescript | | Unified Standard | No — each project rolls its own | Yes — same schema, annotations, ACL across all integrations | | Behavioral Annotations | None or minimal | readonly, destructive, requires_approval, idempotent, open_world | | Access Control | None | Pattern-based ACL with role support | | Audit Trail | None | Built-in tracing, metrics, structured logging | | Cross-Language | Per-language silos | Python and TypeScript with identical behavior |

Core Problem

Traditional module development faces a fundamental contradiction:

Traditional modules: Code can call, but AI cannot understand
AI-Perceivable modules: Code can call, AI can also perceive and understand

AI has become an important caller in software systems, but most modules lack AI-understandable metadata. apcore fundamentally solves this by enforcing input_schema / output_schema / description.

One-Sentence Summary

apcore solves how to build modules (module standard), not how to call tools (communication protocol). Once modules are built, they can be called by code / AI / HTTP / CLI / MCP or any other means.

Why AI-Perceivable?

Once perceived by the AI, it becomes understood, and the AI knows exactly how to act.

Perceivable by AI → Understandable by AI → Usable by AI

| Stage | Meaning | apcore Mechanism | |-------|---------|-----------------| | Perceived | AI can discover and read the module | Schema-enforced description, input_schema, output_schema | | Understood | AI knows when and how to use it | Behavioral annotations (x-when-to-use, x-common-mistakes) | | Executed | AI invokes it correctly and recovers from errors | ai_guidance, requires_approval, self-healing |

The AI Collaboration Lifecycle

apcore organizes module metadata into a coherent lifecycle that guides an Agent through every stage of a task:

Discovery (Identity) — description: Helps the Agent find the right tool for its intent.
Strategy (Wisdom) — metadata: Teaches the Agent when and how to use the tool correctly (e.g., x-when-to-use, x-common-mistakes).
Governance (Safety) — requires_approval: Sets the safety boundary for sensitive operations.
Recovery (Resilience) — ai_guidance: Provides a clear path for the Agent to fix errors autonomously.

Real-World Scenarios

| Scenario | Without apcore | With apcore | |------|------------|------------| | LLM calling your business functions | Manually write tool descriptions, map parameters | Schema auto-provided, LLM understands directly | | New team members onboarding | Read source code, guess parameters | Clear from Schema + annotations | | Cross-team module reuse | Outdated docs, unclear interfaces | Schema is doc, enforced validation | | Security audit | Manually trace call relationships | ACL + call chain auto-tracked | | Expose as MCP Server | Rewrite interface definitions | Adapter reads Schema directly |

Design Decision

Reality: AI has become a key caller in software systems
Decision: Enforce input_schema / output_schema / description
Result: Modules understandable by both humans and AI, no extra cost

Core Principles

| Principle | Description | |------|------| | Schema-Driven | All modules enforce input_schema / output_schema / description | | Directory as ID | Directory path auto-maps to module ID, zero config | | AI-Perceivable | Schema enables AI/LLM perception and understanding—a design requirement, not optional | | Universal Standard | Modules callable by code/AI/HTTP/CLI or any other means | | Progressive Integration | Existing code gains AI-Perceivable capability via decorators, function calls, or YAML binding | | Cross-Language Spec | Language-agnostic protocol specification, any language can implement conformant SDK |

Differences from Traditional Frameworks

| | Traditional Frameworks | apcore | |---|---------|--------| | Schema | Optional | Enforced | | AI-Perceivable | Not guaranteed | Guaranteed | | Module Discovery | Manual registration | Auto-discovery from directory | | Input Validation | Implement yourself | Framework automatic | | Behavior Annotations | None | readonly / destructive / requires_approval etc. | | Call Tracing | Implement yourself | trace_id auto-propagated |

Architecture Overview

apcore's architecture consists of two orthogonal dimensions: **Framework Tech

Apcore

Install / Use

README