Docs: Add Project Wiki and Roadmap v4

docs/wiki.md

@@ -0,0 +1,44 @@
+# PapiAI Project Wiki
+
+## Project Overview
+
+**PapiAI Core** is a robust, type-safe PHP library designed for building AI agents. It provides a unified interface for interacting with various Large Language Models (LLMs) while handling the complexities of tool calling, structured output, and conversation state management.
+
+The library is framework-agnostic, meaning it can be dropped into any PHP 8.2+ project, whether it's a standalone script, a Laravel application, or a Symfony microservice.
+
+### Key Concepts
+
+*   **Agent**: The central orchestrator that manages instructions, tools, and the provider connection.
+*   **Provider**: An abstraction layer for AI models (currently supporting Anthropic and Google Gemini).
+*   **Tool**: Capabilities given to the agent, defined as simple functions or class methods with attributes.
+*   **Schema**: A Zod-like fluent interface for defining structured output requirements.
+*   **Stream**: First-class support for real-time streaming of text and tool execution events.
+
+## Roadmap
+
+This roadmap outlines the development phases for PapiAI, moving from the current foundational state to a full-featured AI ecosystem.
+
+### Phase 1: Foundation (Current Status)
+*   [x] Core `Agent` logic and conversation management.
+*   [x] Provider interfaces for Anthropic (Claude) and Google (Gemini).
+*   [x] Function and Class-based Tool definitions.
+*   [x] Structured output validation using Schemas.
+*   [x] Event-based streaming support.
+*   [x] Basic test suite with Pest.
+
+### Phase 2: Expansion & Integration
+*   [ ] **OpenAI Provider**: Add support for GPT-4o and o1 models.
+*   [ ] **Memory Management**: Implement interfaces for short-term and long-term memory (Redis, Vector DBs).
+*   [ ] **Middleware Pipelines**: Allow intercepting requests/responses for logging, moderation, or modification.
+*   [ ] **Http Client Abstraction**: Decouple from specific HTTP clients to allow deeper customization.
+
+### Phase 3: Developer Experience
+*   [ ] **Laravel Bundle**: dedicated service providers, facades, and artisan commands.
+*   [ ] **Symfony Bundle**: Dependency injection configuration and debug toolbar integration.
+*   [ ] **CLI Mode**: Run agents directly from the command line for testing and automation.
+*   [ ] **Documentation Site**: Comprehensive static site with API references and cookbooks.
+
+### Phase 4: Advanced Features
+*   [ ] **Multi-Agent Orchestration**: Patterns for agents to communicate and delegate tasks to one another.
+*   [ ] **Evaluations**: Tools for measuring agent performance and accuracy against test sets.
+*   [ ] **Observability Dashboard**: specialized UI for tracing agent thoughts and tool executions.

papi-core/docs/WIKI.md

@@ -0,0 +1,63 @@
+# PapiAI Project Wiki
+
+## 1. Project Overview
+
+**PapiAI** is a modern, framework-agnostic PHP library designed for building robust AI agents. It provides a unified interface to interact with various Large Language Models (LLMs) like Anthropic Claude and Google Gemini, making it easy to integrate AI capabilities into any PHP application (Laravel, Symfony, or standalone).
+
+### Key Philosophy
+- **Simplicity**: Clean, intuitive API for creating agents.
+- **Type Safety**: Built on PHP 8.2+ with strict typing.
+- **Modularity**: Core logic is separated from specific provider implementations.
+
+## 2. Architecture
+
+The project is structured around a few key abstractions:
+
+### Core Components (`papi-ai/papi-core`)
+- **Agent**: The main entry point. It orchestrates interactions between the user, the LLM provider, and available tools.
+- **ProviderInterface**: The contract that all LLM providers must implement. It standardizes:
+  - `chat()`: Standard request/response.
+  - `stream()`: Real-time streaming responses.
+  - Capabilities: `supportsTool()`, `supportsVision()`, `supportsStructuredOutput()`.
+- **Tool**: encapsulations of functions or class methods that the AI can "call" to perform actions (e.g., fetching weather, querying a database).
+- **Schema**: A fluent builder (Zod-like) for defining structured output requirements, ensuring the AI returns data in a predictable format.
+
+### Providers
+Specific implementations are handled in separate packages to keep the core lightweight:
+- `papi-ai/anthropic`: Adapter for Anthropic's Claude models.
+- `papi-ai/google`: Adapter for Google's Gemini models.
+- `papi-ai/openai`: (Planned/In-progress) Adapter for OpenAI.
+
+## 3. Getting Started
+
+### Installation
+Install the core package and your desired provider:
+
+```bash
+composer require papi-ai/core
+composer require papi-ai/anthropic
+```
+
+### Basic Usage
+Here is how to create a simple agent using Claude:
+
+```php
+use PapiAI\Core\Agent;
+use PapiAI\Anthropic\AnthropicProvider;
+
+$agent = new Agent(
+    provider: new AnthropicProvider(apiKey: $_ENV['ANTHROPIC_API_KEY']),
+    model: 'claude-3-5-sonnet-20240620',
+    instructions: 'You are a helpful coding assistant.'
+);
+
+$response = $agent->run('Refactor this class for me...');
+echo $response->text;
+```
+
+## 4. Advanced Features
+
+- **Tool Calling**: Define PHP functions or class methods as tools. The Agent handles the LLM's request to execute them.
+- **Structured Output**: Enforce JSON schemas on responses for reliable data extraction.
+- **Streaming**: Subscribe to event streams for real-time UI updates.
+- **Observability**: Hooks available for logging and monitoring agent performance.