nvoos / core
Framework-agnostic AI orchestration engine — agentic loop, tool registry, provider routing, SSE streaming.
Requires
- php: ^8.1
Requires (Dev)
- mockery/mockery: ^1.6
- phpstan/phpstan: ^1.10
- phpstan/phpstan-phpunit: ^1.4
- phpunit/phpunit: ^10.0 || ^11.0
Suggests
- nvoos/craft-adapter: Craft CMS integration via the adapter layer
- nvoos/laravel-adapter: Laravel integration via the adapter layer
- nvoos/wordpress-adapter: WordPress integration via the adapter layer
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-17 03:49:55 UTC
README
Framework-agnostic AI orchestration engine — agentic loop, tool registry, provider routing, SSE streaming.
Installation
composer require nvoos/core
Requires PHP 8.1+.
What's Inside
- Domain layer — 9 contracts (ports), 10 immutable entities, 5 typed exceptions, 8 PSR-14 domain events
- Application layer —
ChatOrchestrator(agentic loop),ProviderRouter(12-provider routing),ToolRegistry,SkillRegistry - Infrastructure layer — 12 AI provider clients (OpenAI, Gemini, Anthropic, Ollama, DeepSeek, etc.), SSE streaming handler, cost calculator
- Tools — 43 framework-agnostic tool classes (content, cache, files, settings, jobs, etc.)
Architecture
This package uses Hexagonal Architecture (Ports & Adapters). The core engine defines interfaces (ports) that platform-specific adapters implement:
| Adapter | Package |
|---|---|
| WordPress | nvoos/wordpress-adapter |
| Laravel | nvoos/laravel-adapter |
| Craft CMS | nvoos/craft-adapter |
Typed tool results
Tools have two surfaces. The untyped one (ToolInterface::execute()) is the
legacy contract used by the registry pipeline. The typed one
(ToolResultInterface::executeResult()) returns a ToolResult ADT — success
with a payload, or failure with a DomainError. Nothing is optional or
un-inspectable.
use Nvoos\Core\Tool\AbstractResultTool; use Nvoos\Core\Domain\ValueObject\ToolResult; final class MyTool extends AbstractResultTool { public function getSlug(): string { return 'my_tool'; } public function getName(): string { return 'My Tool'; } public function getDescription(): string { return 'Does one thing.'; } public function getParametersSchema(): array { return array( 'type' => 'object' ); } public function executeResult( array $arguments = array(), array $context = array() ): ToolResult { $name = $this->optionParam( $arguments, 'name' ) ->map( static fn( $v ) => trim( (string) $v ) ) ->getOrElse( 'world' ); return ToolResult::success( "Hello, {$name}.", array( 'name' => $name ) ); } }
execute() is inherited and final: it converts the result to the canonical
envelope on success and to the platform error (WP_Error in WordPress) on
failure, so guards, waterfalls, observers, and the canonical-envelope sniff all
keep working unchanged.
Typed helpers on the base class:
| Helper | Replaces | Behaviour |
|---|---|---|
optionParam() |
requireParam() |
Option — distinguishes absent from present-but-falsy |
authorize() |
requireCapability() |
Throws AccessDeniedException; the registry converts it |
validationFailure() |
errors->validationFailed() |
ToolResult failure with the same payload (422 + field errors) |
unwrapResult() |
— | ToolResult → legacy envelope/error |
At the registry edge, ToolRegistry::executeResult() returns a ToolResult
for any tool (typed or legacy), and ToolRegistry::toResult() is the only
place a platform error becomes a DomainError.
Usage
use Nvoos\Core\Application\Chat\ChatOrchestrator; use Nvoos\Core\Application\Provider\ProviderRouter; use Nvoos\Core\Application\Tool\ToolRegistry; // Wire up adapters (WordPress example) $toolRegistry = new ToolRegistry($errorFactory, $eventDispatcher); $providerRouter = new ProviderRouter($settingsStore, $httpClient, $requestFactory); $orchestrator = new ChatOrchestrator( $toolRegistry, $providerRouter, $eventDispatcher, $errorFactory, ); // Run a chat $response = $orchestrator->handleChat($messages, $options);
License
MIT — see LICENSE.