# papi-ai/papi-core architecture

> Architecture diagram of the GitHub repository papi-ai/papi-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/papi-ai/papi-core
- Repository: https://github.com/papi-ai/papi-core

## Overview

PapiAI Core is a framework-agnostic PHP library for building provider-neutral AI agents. The main workflow is an application prompt entering an Agent, which calls a provider, may dispatch model-requested tools over multiple turns, and returns a response; streaming is a separate agent path. The graph also preserves documented schemas, conversation handling, middleware, and the broader provider contracts visible in the tree. Some capabilities are represented only by interfaces or README descriptions, so their implementation links are not inferred.

Main entry points: [`src/Agent.php`](https://github.com/papi-ai/papi-core/blob/main/src/Agent.php) (Agent), [`src/Tool.php`](https://github.com/papi-ai/papi-core/blob/main/src/Tool.php) (Tool Definitions), [`src/Conversation.php`](https://github.com/papi-ai/papi-core/blob/main/src/Conversation.php) (Conversation), [`src/AgentBuilder.php`](https://github.com/papi-ai/papi-core/blob/main/src/AgentBuilder.php) (Agent Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent Runtime"]
  node_agent["Agent<br/>[Agent.php]"]
  node_builder["Agent Builder<br/>[AgentBuilder.php]"]
  node_provider["Provider Contract"]
  node_middleware["Middleware"]
  node_middleware_impls["Middleware Implementations"]
  node_request["Agent Request<br/>[AgentRequest.php]"]
end

subgraph group_extensions["Tools &amp; Middleware"]
  node_tools["Tool Definitions<br/>[Tool.php]"]
  node_tool_contract["Tool Contract<br/>[ToolInterface.php]"]
  node_attributes["Tool Attributes"]
end

subgraph group_conversation["Conversation &amp; Output"]
  node_conversation["Conversation<br/>[Conversation.php]"]
  node_messages["Messages<br/>[Message.php]"]
  node_schema["Structured Schemas<br/>[Schema.php]"]
  node_response["Agent Response<br/>[Response.php]"]
  node_streaming["Streaming Events<br/>[StreamEvent.php]"]
  node_conversation_store[("Conversation Store")]
end

subgraph group_capabilities["Provider Capabilities"]
  node_multimodal["Media &amp; Model Contracts"]
  node_embedding["Embedding Response"]
  node_vector_store[("Vector Store")]
  node_search_result["Search Result<br/>[SearchResult.php]"]
  node_token_optimisation["Token Optimisation Contract"]
end

node_application(("Application"))
node_provider_service["Provider Service"]

node_application -->|"runs prompt"| node_agent
node_application -->|"configures agent"| node_builder
node_builder -->|"constructs"| node_agent
node_agent -->|"requests completion"| node_provider_service
node_agent -->|"dispatches tool calls"| node_tools
node_tools -->|"implements"| node_tool_contract
node_tools -->|"reads attributes"| node_attributes
node_agent -->|"passes requests"| node_middleware
node_middleware_impls -->|"implements"| node_middleware
node_agent -->|"creates request"| node_request
node_agent -->|"validates output"| node_schema
node_agent -->|"returns response"| node_response
node_agent -->|"emits events"| node_streaming
node_conversation -->|"manages messages"| node_messages
node_application -->|"builds history"| node_conversation
node_conversation_store -->|"loads and saves"| node_conversation
node_provider_service -.->|"implements contract"| node_provider
node_provider_service -.->|"may implement"| node_multimodal
node_embedding -.->|"models embedding result"| node_multimodal
node_vector_store -->|"returns matches"| node_search_result
node_application -.->|"may integrate"| node_token_optimisation

click node_agent "https://github.com/papi-ai/papi-core/blob/main/src/Agent.php"
click node_builder "https://github.com/papi-ai/papi-core/blob/main/src/AgentBuilder.php"
click node_provider "https://github.com/papi-ai/papi-core/blob/main/src/Contracts/ProviderInterface.php"
click node_middleware "https://github.com/papi-ai/papi-core/blob/main/src/Contracts/MiddlewareInterface.php"
click node_middleware_impls "https://github.com/papi-ai/papi-core/tree/main/src/Middleware"
click node_request "https://github.com/papi-ai/papi-core/blob/main/src/AgentRequest.php"
click node_tools "https://github.com/papi-ai/papi-core/blob/main/src/Tool.php"
click node_tool_contract "https://github.com/papi-ai/papi-core/blob/main/src/Contracts/ToolInterface.php"
click node_attributes "https://github.com/papi-ai/papi-core/tree/main/src/Attributes"
click node_conversation "https://github.com/papi-ai/papi-core/blob/main/src/Conversation.php"
click node_messages "https://github.com/papi-ai/papi-core/blob/main/src/Message.php"
click node_schema "https://github.com/papi-ai/papi-core/blob/main/src/Schema/Schema.php"
click node_response "https://github.com/papi-ai/papi-core/blob/main/src/Response.php"
click node_streaming "https://github.com/papi-ai/papi-core/blob/main/src/StreamEvent.php"
click node_conversation_store "https://github.com/papi-ai/papi-core/blob/main/src/Storage/FileConversationStore.php"
click node_multimodal "https://github.com/papi-ai/papi-core/tree/main/src/Contracts"
click node_embedding "https://github.com/papi-ai/papi-core/blob/main/src/EmbeddingResponse.php"
click node_vector_store "https://github.com/papi-ai/papi-core/blob/main/src/VectorStore/InMemoryVectorStore.php"
click node_search_result "https://github.com/papi-ai/papi-core/blob/main/src/SearchResult.php"
click node_token_optimisation "https://github.com/papi-ai/papi-core/blob/main/src/Contracts/LLMTokenOptimisationProxyInterface.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent,node_builder,node_provider,node_middleware,node_middleware_impls,node_request toneBlue
class node_tools,node_tool_contract,node_attributes toneAmber
class node_conversation,node_messages,node_schema,node_response,node_streaming,node_conversation_store toneMint
class node_multimodal,node_embedding,node_vector_store,node_search_result,node_token_optimisation toneRose
class node_application,node_provider_service toneIndigo
```

## Components

### Agent Runtime

- [Agent](https://github.com/papi-ai/papi-core/blob/main/src/Agent.php): `src/Agent.php`
- [Agent Builder](https://github.com/papi-ai/papi-core/blob/main/src/AgentBuilder.php): `src/AgentBuilder.php`
- [Provider Contract](https://github.com/papi-ai/papi-core/blob/main/src/Contracts/ProviderInterface.php): `src/Contracts/ProviderInterface.php`
- [Middleware](https://github.com/papi-ai/papi-core/blob/main/src/Contracts/MiddlewareInterface.php): `src/Contracts/MiddlewareInterface.php`
- [Middleware Implementations](https://github.com/papi-ai/papi-core/tree/main/src/Middleware): `src/Middleware`
- [Agent Request](https://github.com/papi-ai/papi-core/blob/main/src/AgentRequest.php): `src/AgentRequest.php`

### Tools & Middleware

- [Tool Definitions](https://github.com/papi-ai/papi-core/blob/main/src/Tool.php): `src/Tool.php`
- [Tool Contract](https://github.com/papi-ai/papi-core/blob/main/src/Contracts/ToolInterface.php): `src/Contracts/ToolInterface.php`
- [Tool Attributes](https://github.com/papi-ai/papi-core/tree/main/src/Attributes): `src/Attributes`

### Conversation & Output

- [Conversation](https://github.com/papi-ai/papi-core/blob/main/src/Conversation.php): `src/Conversation.php`
- [Messages](https://github.com/papi-ai/papi-core/blob/main/src/Message.php): `src/Message.php`
- [Structured Schemas](https://github.com/papi-ai/papi-core/blob/main/src/Schema/Schema.php): `src/Schema/Schema.php`
- [Agent Response](https://github.com/papi-ai/papi-core/blob/main/src/Response.php): `src/Response.php`
- [Streaming Events](https://github.com/papi-ai/papi-core/blob/main/src/StreamEvent.php): `src/StreamEvent.php`
- [Conversation Store](https://github.com/papi-ai/papi-core/blob/main/src/Storage/FileConversationStore.php): `src/Storage/FileConversationStore.php`

### Provider Capabilities

- [Media & Model Contracts](https://github.com/papi-ai/papi-core/tree/main/src/Contracts): `src/Contracts`
- [Embedding Response](https://github.com/papi-ai/papi-core/blob/main/src/EmbeddingResponse.php): `src/EmbeddingResponse.php`
- [Vector Store](https://github.com/papi-ai/papi-core/blob/main/src/VectorStore/InMemoryVectorStore.php): `src/VectorStore/InMemoryVectorStore.php`
- [Search Result](https://github.com/papi-ai/papi-core/blob/main/src/SearchResult.php): `src/SearchResult.php`
- [Token Optimisation Contract](https://github.com/papi-ai/papi-core/blob/main/src/Contracts/LLMTokenOptimisationProxyInterface.php): `src/Contracts/LLMTokenOptimisationProxyInterface.php`

### Other components

- **Application**
- **Provider Service**

## Connections

- Application → Agent: runs prompt (evidence: `README.md`)
- Application → Agent Builder: configures agent (evidence: `README.md`)
- Agent Builder → Agent: constructs (evidence: `src/AgentBuilder.php`)
- Agent → Provider Service: requests completion (evidence: `src/Agent.php`)
- Agent → Tool Definitions: dispatches tool calls (evidence: `src/Agent.php`)
- Tool Definitions → Tool Contract: implements (evidence: `src/Tool.php`)
- Tool Definitions → Tool Attributes: reads attributes (evidence: `src/Tool.php`)
- Agent → Middleware: passes requests (evidence: `src/Agent.php`)
- Middleware Implementations → Middleware: implements (evidence: `src/Middleware/CacheMiddleware.php`)
- Agent → Agent Request: creates request (evidence: `src/Agent.php`)
- Agent → Structured Schemas: validates output (evidence: `src/Agent.php`)
- Agent → Agent Response: returns response (evidence: `src/Agent.php`)
- Agent → Streaming Events: emits events (evidence: `README.md`)
- Conversation → Messages: manages messages (evidence: `src/Conversation.php`)
- Application → Conversation: builds history (evidence: `README.md`)
- Conversation Store → Conversation: loads and saves (evidence: `src/Storage/FileConversationStore.php`)
- Provider Service → Provider Contract: implements contract (evidence: `README.md`)
- Provider Service → Media & Model Contracts: may implement
- Embedding Response → Media & Model Contracts: models embedding result (evidence: `src/Contracts/EmbeddingProviderInterface.php`)
- Vector Store → Search Result: returns matches (evidence: `src/VectorStore/InMemoryVectorStore.php`)
- Application → Token Optimisation Contract: may integrate (evidence: `src/Contracts/LLMTokenOptimisationProxyInterface.php`)