Merge pull request #21 from carmelosantana/chore_cleanup-sse-stream

Improves SseStreamParser for handling various SSE scenarios

Author: carmelosantana

README.md

@@ -30,12 +30,13 @@ graph LR
 - **Streaming + tool calls** — all providers support streaming with assembled tool call deltas
 - **Structured output** — extract typed data from LLMs via JSON mode (OpenAI) or tool-use trick (Anthropic)
 - **Image input** — send images to vision models via base64, URL, or file path (auto-converts between provider formats; URLs pre-downloaded for providers that don't support them natively)
-- **Bundled agents** — `FileAgent`, `WebAgent`, `CodeAgent` ready to use out of the box
+- **Bundled agents** — `FileAgent`, `WebAgent`, `CodeAgent` for quick prototyping *(deprecated — use `AbstractAgent` with toolkits for production)*
 - **Composable toolkits** — filesystem, web, shell, and memory toolkits that snap onto any agent
 - **Context window management** — automatic conversation pruning when approaching token limits
 - **Observer pattern** — attach `SplObserver` to watch agent lifecycle events in real time
 - **Security by default** — path traversal protection, SSRF blocking, shell injection detection
 - **OpenClaw config** — centralized model routing with aliases, fallbacks, and per-provider settings
+- **PSR-3 logging** — optional `LoggerInterface` on all providers for diagnostic visibility
 - **Zero framework coupling** — depends only on `symfony/http-client` and `psr/log`
 
 ## Provider Feature Matrix
@@ -78,26 +79,44 @@ declare(strict_types=1);
 
 require 'vendor/autoload.php';
 
-use CarmeloSantana\PHPAgents\Agent\FileAgent;
+use CarmeloSantana\PHPAgents\Agent\AbstractAgent;
+use CarmeloSantana\PHPAgents\Contract\ProviderInterface;
 use CarmeloSantana\PHPAgents\Provider\OllamaProvider;
+use CarmeloSantana\PHPAgents\Toolkit\FilesystemToolkit;
 use CarmeloSantana\PHPAgents\Message\UserMessage;
 
-$provider = new OllamaProvider(model: 'llama3.2');
+// Create a simple file agent using AbstractAgent + FilesystemToolkit
+final class MyFileAgent extends AbstractAgent
+{
+    public function __construct(ProviderInterface $provider, string $rootPath)
+    {
+        parent::__construct($provider);
+        $this->addToolkit(new FilesystemToolkit($rootPath, readOnly: true));
+    }
 
-$agent = new FileAgent(
-    provider: $provider,
-    rootPath: getcwd(),
-    readOnly: true,
-);
+    public function instructions(): string
+    {
+        return 'You are a helpful file assistant. Read and summarize files when asked.';
+    }
+
+    public function name(): string
+    {
+        return 'FileAgent';
+    }
+}
 
+$provider = new OllamaProvider(model: 'llama3.2');
+$agent = new MyFileAgent($provider, getcwd());
 $output = $agent->run(new UserMessage('Summarize the README.md file.'));
 
 echo $output->content . "\n";
 ```
 
 > Make sure Ollama is running: `ollama serve` and a model is pulled: `ollama pull llama3.2`
 
-## Bundled Agents
+## Bundled Agents (Deprecated)
+
+> **Note:** Bundled agents are deprecated and will be removed in 1.0. Use `AbstractAgent` with composable toolkits instead (see [Creating Custom Agents](#creating-custom-agents)).
 
 | Agent       | Description                                                        | Toolkits                             |
 | ----------- | ------------------------------------------------------------------ | ------------------------------------ |

composer.json

@@ -47,12 +47,6 @@
     "minimum-stability": "stable",
     "prefer-stable": true,
     "extra": {
-        "php-agents": {
-            "agents": [
-                "CarmeloSantana\\PHPAgents\\Agent\\FileAgent",
-                "CarmeloSantana\\PHPAgents\\Agent\\WebAgent",
-                "CarmeloSantana\\PHPAgents\\Agent\\CodeAgent"
-            ]
-        }
+        "php-agents": {}
     }
 }

docs/AGENTS.md

@@ -102,39 +102,42 @@ flowchart TD
     LOOP --> NOTIFY_DONE[notify: agent.done]
 ```
 
-## Built-in Agents
+## Built-in Agents (Deprecated)
 
-### FileAgent
+> **Deprecated.** `FileAgent`, `WebAgent`, and `CodeAgent` will be removed in 1.0. Use `AbstractAgent` with explicit toolkits instead — this gives you full control over which tools are available.
 
-Pre-loaded with `FilesystemToolkit`. Good for file manipulation tasks.
+### FileAgent
 
 ```php
-use CarmeloSantana\PHPAgents\Agent\FileAgent;
-
-$agent = new FileAgent(provider: $provider);
-// Has: read_file, write_file, list_directory, search_files, file_info, create_directory, delete_file
+// DEPRECATED — use AbstractAgent + FilesystemToolkit instead:
+$agent = new class($provider) extends AbstractAgent {
+    public function name(): string { return 'File Agent'; }
+    public function instructions(): string { return 'You manage files.'; }
+};
+$agent->addToolkit(new FilesystemToolkit('/path/to/root'));
 ```
 
 ### WebAgent
 
-Pre-loaded with `WebToolkit`. Good for web research and API interaction.
-
 ```php
-use CarmeloSantana\PHPAgents\Agent\WebAgent;
-
-$agent = new WebAgent(provider: $provider);
-// Has: http_request, web_search
+// DEPRECATED — use AbstractAgent + WebToolkit instead:
+$agent = new class($provider) extends AbstractAgent {
+    public function name(): string { return 'Web Agent'; }
+    public function instructions(): string { return 'You research the web.'; }
+};
+$agent->addToolkit(new WebToolkit());
 ```
 
 ### CodeAgent
 
-Pre-loaded with `FilesystemToolkit` and `ShellToolkit`. Good for coding tasks.
-
 ```php
-use CarmeloSantana\PHPAgents\Agent\CodeAgent;
-
-$agent = new CodeAgent(provider: $provider);
-// Has: file tools + execute_command
+// DEPRECATED — use AbstractAgent + FilesystemToolkit + ShellToolkit instead:
+$agent = new class($provider) extends AbstractAgent {
+    public function name(): string { return 'Code Agent'; }
+    public function instructions(): string { return 'You write and execute code.'; }
+};
+$agent->addToolkit(new FilesystemToolkit('/path/to/root'));
+$agent->addToolkit(new ShellToolkit());
 ```
 
 ## Adding Tools and Toolkits
@@ -145,7 +148,7 @@ $agent->addTool($myTool);
 
 // Add a toolkit (registers all its tools + injects guidelines)
 $agent->addToolkit(new WebToolkit());
-$agent->addToolkit(new MemoryToolkit(memory: $memory));
+$agent->addToolkit(new MemoryToolkit(memory: $memory)); // Note: MemoryToolkit is deprecated — use a database-backed implementation
 ```
 
 Tools from toolkits are merged with directly-added tools. Guidelines from all toolkits are concatenated and appended to the system prompt.
@@ -218,7 +221,7 @@ final class TimeoutToken implements CancellationTokenInterface
     }
 }
 
-$agent = new FileAgent(
+$agent = new MyAgent(
     provider: $provider,
     cancellationToken: new TimeoutToken(30),
 );
@@ -254,7 +257,7 @@ final class QueuedInputProvider implements PendingInputProviderInterface
 }
 
 $inputProvider = new QueuedInputProvider();
-$agent = new FileAgent(
+$agent = new MyAgent(
     provider: $provider,
     pendingInputProvider: $inputProvider,
 );
@@ -277,7 +280,7 @@ $contextWindow = new ContextWindow(
     reservedTokens: 4_000, // Space for the response
 );
 
-$agent = new FileAgent(
+$agent = new MyAgent(
     provider: $provider,
     contextWindow: $contextWindow,
 );

docs/ARCHITECTURE.md

@@ -13,9 +13,9 @@ graph TB
     subgraph "php-agents Framework"
         subgraph "Agent Layer"
             AA[AbstractAgent]
-            FA[FileAgent]
-            WA[WebAgent]
-            CA[CodeAgent]
+            FA[FileAgent<br/><i>deprecated</i>]
+            WA[WebAgent<br/><i>deprecated</i>]
+            CA[CodeAgent<br/><i>deprecated</i>]
             FA --> AA
             WA --> AA
             CA --> AA
@@ -38,7 +38,7 @@ graph TB
             FST[FilesystemToolkit]
             WT[WebToolkit]
             ST[ShellToolkit]
-            MT[MemoryToolkit]
+            MT[MemoryToolkit<br/><i>deprecated</i>]
             T --> TI
             FST --> TK
             WT --> TK
@@ -130,11 +130,14 @@ flowchart TD
 Agents are composed from providers, toolkits, and policies rather than inheriting complex behavior:
 
 ```php
-$agent = new FileAgent(
+$agent = new class(
     provider: new OllamaProvider(model: 'llama3.2'),
     maxIterations: 10,
     executionPolicy: new MyPolicy(),
-);
+) extends AbstractAgent {
+    public function name(): string { return 'My Agent'; }
+    public function instructions(): string { return 'You help users.'; }
+};
 ```
 
 ### Interface-Driven Extensibility
@@ -150,7 +153,7 @@ Every major component has an interface contract. You can replace any layer:
 | `CancellationTokenInterface` | Cooperative cancellation | `NullCancellationToken` |
 | `PendingInputProviderInterface` | External input injection | `NullPendingInputProvider` |
 | `ContextWindowInterface` | Token budget tracking | `ContextWindow` |
-| `MemoryInterface` | Persistent memory | `FileMemory` |
+| `MemoryInterface` | Persistent memory | `FileMemory` *(deprecated)* |
 | `VectorStoreInterface` | Similarity search | `InMemoryVectorStore` |
 | `EmbeddingProviderInterface` | Text → vector | Ollama, OpenAI |
 | `TokenCounterInterface` | Token counting | `HeuristicCounter`, `TiktokenCounter` |
@@ -379,12 +382,12 @@ flowchart LR
 ```mermaid
 graph TB
     subgraph "Agent-Facing"
-        MTK[MemoryToolkit]
+        MTK[MemoryToolkit<br/><i>deprecated</i>]
     end
 
     subgraph "Storage Layer"
         MI[MemoryInterface]
-        FM[FileMemory<br/>Markdown file]
+        FM[FileMemory<br/><i>deprecated</i>]
     end
 
     subgraph "Vector Search"

docs/GETTING-STARTED.md

@@ -41,13 +41,16 @@ composer require hkulekci/qdrant
 
    require __DIR__ . '/vendor/autoload.php';
 
-   use CarmeloSantana\PHPAgents\Agent\FileAgent;
+   use CarmeloSantana\PHPAgents\Agent\AbstractAgent;
    use CarmeloSantana\PHPAgents\Message\UserMessage;
    use CarmeloSantana\PHPAgents\Provider\OllamaProvider;
+   use CarmeloSantana\PHPAgents\Toolkit\FilesystemToolkit;
 
-   $agent = new FileAgent(
-       provider: new OllamaProvider(model: 'llama3.2'),
-   );
+   $agent = new class(provider: new OllamaProvider(model: 'llama3.2')) extends AbstractAgent {
+       public function name(): string { return 'File Agent'; }
+       public function instructions(): string { return 'You manage files in the workspace.'; }
+   };
+   $agent->addToolkit(new FilesystemToolkit(__DIR__));
 
    $output = $agent->run(new UserMessage('List the files in the current directory'));
    echo $output->content;
@@ -100,14 +103,16 @@ declare(strict_types=1);
 
 require __DIR__ . '/vendor/autoload.php';
 
-use CarmeloSantana\PHPAgents\Agent\FileAgent;
+use CarmeloSantana\PHPAgents\Agent\AbstractAgent;
 use CarmeloSantana\PHPAgents\Message\UserMessage;
 use CarmeloSantana\PHPAgents\Provider\OllamaProvider;
+use CarmeloSantana\PHPAgents\Toolkit\FilesystemToolkit;
 
-$agent = new FileAgent(
-    provider: new OllamaProvider(model: 'llama3.2'),
-    maxIterations: 15,
-);
+$agent = new class(provider: new OllamaProvider(model: 'llama3.2'), maxIterations: 15) extends AbstractAgent {
+    public function name(): string { return 'File Agent'; }
+    public function instructions(): string { return 'You manage files in the workspace.'; }
+};
+$agent->addToolkit(new FilesystemToolkit(__DIR__));
 
 $output = $agent->run(
     new UserMessage('Create a file called hello.txt with the contents "Hello, World!"'),
@@ -117,7 +122,7 @@ echo $output->content;
 // Agent creates the file using FilesystemToolkit tools, then responds
 ```
 
-The `FileAgent` comes pre-loaded with `FilesystemToolkit` (file read/write/list/search/delete) tools. The agent loop works like this:
+The agent is pre-loaded with `FilesystemToolkit` (file read/write/list/search/delete) tools. The agent loop works like this:
 
 1. Your message is sent to the LLM with tool definitions
 2. The LLM decides which tool to call (e.g., `write_file`)

docs/MEMORY.md

@@ -1,5 +1,7 @@
 # Memory
 
+> **Deprecated.** `FileMemory`, `MemoryToolkit`, and the `MemoryInterface` in php-agents will be removed in 1.0. For production use, implement a database-backed memory store (e.g. Coqui's SQLite-backed `MemoryStore`). The vector store layer (`VectorStoreInterface`, `InMemoryVectorStore`, embedding providers) is **not** deprecated.
+
 php-agents provides a layered memory system: simple key-value storage, persistent file-backed memory, and vector similarity search for semantic retrieval.
 
 ## Architecture
@@ -58,7 +60,9 @@ interface MemoryInterface
 }
 ```
 
-## FileMemory
+## FileMemory (Deprecated)
+
+> **Deprecated.** Use a database-backed implementation instead. Will be removed in 1.0.
 
 Persists memories to a Markdown file. Each entry is a third-level heading with the key as the title and the value as the body:
 
@@ -117,7 +121,9 @@ sequenceDiagram
 
 `FileMemory::search()` performs simple substring matching on keys and values. For semantic search, use a vector store.
 
-## MemoryToolkit
+## MemoryToolkit (Deprecated)
+
+> **Deprecated.** Use a database-backed memory toolkit instead. Will be removed in 1.0.
 
 Exposes memory operations as tools the agent can use:
 

docs/PROVIDERS.md

@@ -469,6 +469,61 @@ Both URL and base64 data URI images are supported.
 |----------|---------|
 | `MISTRAL_API_KEY` | `MistralProvider` |
 
+## Shared Provider Utilities
+
+### PSR-3 Logging
+
+All providers accept an optional `Psr\Log\LoggerInterface` via their constructor. When provided, errors in non-critical paths (model listing, health checks, image downloads) are logged instead of silently swallowed:
+
+```php
+use Monolog\Logger;
+use Monolog\Handler\StreamHandler;
+
+$logger = new Logger('providers');
+$logger->pushHandler(new StreamHandler('php://stderr'));
+
+$provider = new OllamaProvider(
+    model: 'llama3.2',
+    logger: $logger,
+);
+```
+
+### SseStreamParser
+
+Shared SSE line-buffering parser used by all streaming providers. Handles chunk boundary splits, `[DONE]` sentinels, and malformed JSON gracefully:
+
+```php
+use CarmeloSantana\PHPAgents\Provider\SseStreamParser;
+
+$parser = new SseStreamParser($httpClient, $response);
+
+foreach ($parser->events() as $payload) {
+    // $payload is a decoded associative array from each `data: {...}` line
+}
+```
+
+Custom providers can use `SseStreamParser` directly instead of implementing their own SSE buffering logic.
+
+### SchemaUtils
+
+Static helpers for JSON Schema normalization. Each method operates on a single schema node — providers handle their own recursion:
+
+| Method | Purpose |
+|--------|---------|
+| `stripKeywords(array $schema, array $keywords)` | Remove unsupported keywords from a schema node |
+| `flattenCombinator(array $schema, string $combinator)` | Replace `anyOf`/`oneOf`/`allOf` with the first non-null variant |
+| `demoteConstraints(array $schema, array $templates)` | Move constraint metadata (minLength, enum, etc.) into the description field |
+
+```php
+use CarmeloSantana\PHPAgents\Provider\SchemaUtils;
+
+// Strip keywords a provider doesn't support
+$schema = SchemaUtils::stripKeywords($schema, ['additionalProperties', '$schema', 'default']);
+
+// Flatten anyOf to a single type (for providers that don't support union types)
+$schema = SchemaUtils::flattenCombinator($schema, 'anyOf');
+```
+
 ## Creating a Custom Provider
 
 Implement `ProviderInterface` or extend `AbstractProvider`: