Download the PHP package artisanpack-ui/ai without Composer

ArtisanPack UI AI

Shared AI foundation for the ArtisanPack UI ecosystem. Sits alongside artisanpack-ui/core and artisanpack-ui/hooks as a shared layer that other ArtisanPack UI packages can optionally depend on.

Built on top of laravel/ai.

See the AI RFC for design context and the roadmap for downstream feature work.

What this package gives you

• A feature registry — every AI capability across the ecosystem discoverable in one place, with per-feature enable/disable toggles that survive across processes.
• A credential store — bring your own key via .env or the admin UI, encrypted at rest, resolved through a single CredentialResolver contract.
• A cost + usage layer — per-agent event stream, monthly budget cap, dashboard aggregations, budget-warning email.
• A provider-agnostic agent base class — subclass, declare a feature key + output schema, get caching, telemetry, and streaming for free.
• Shared trigger-surface plumbing — one exception ladder (HandlesAiFeatureResponses) and two Livewire concerns (ChecksFeatureToggle, InteractsWithAiFeature) so every controller and component maps AI failures the same way.
• Test doubles — Ai::fake() for scripted agent output and FakeAgentPrompter for canned provider responses, both shipped from src/Testing.
• Livewire admin surfaces — Settings page, Usage dashboard, Per-feature toggles page.
• JSON API endpoints — REST parity for React and Vue starter kits (see docs/reference/api-schema.json).
• Ollama support — every shipped agent works against a self-hosted local model, not just the cloud providers.

Installation

Publish the config if you want to customise defaults:

Quick start

Access the shared foundation via the facade or helper:

Run an agent shipped by any ecosystem package (this example uses artisanpack-ui/seo):

That single call runs the full pipeline: feature-gate check → credential resolution → cache lookup → provider call → telemetry event → cache store. There's no separate setup on the calling side.

Documentation

Start at docs/home.md for the full documentation index. Direct links:

• Getting Started — install, publish config, and run your first agent.
• Authoring agents — how a downstream package adds a new AI capability, worked through with MetaDescriptionAgent as the running example.
• Built-in agents — the cross-cutting agents shipped in this package itself (AltTextGenerationAgent, ContentRewriteAgent, SummarizationAgent) — inputs, output schemas, and consumer notes.
• Bring your own key (BYOK) — env-mode vs. CMS-mode setup, provider-specific notes for Anthropic, OpenAI, Gemini, Groq, and Ollama.
• Overriding — container binding and config override patterns for replacing a shipped agent with your own subclass.
• Trigger surfaces — the shared exception ladder and Livewire concerns for controllers and components that run agents.
• Testing — Ai::fake() and FakeAgentPrompter test doubles.
• React and Vue integration — authentication, base URLs, and streaming for JavaScript clients.
• JSON API schema — OpenAPI 3.1 schema for the REST endpoints that back the React and Vue admin surfaces.

Hooks

The package fires hooks from artisanpack-ui/hooks at the shared prompter seam, so a downstream package can add safety prompts, PII scrubbing, or audit logging uniformly across every agent — no per-agent patching.

$context for the prompt/response/tools hooks carries provider, model, instructions, and attachments (count).

Admin surfaces

Once cms-framework is installed and migrations are run, the following surfaces register automatically under Admin → Packages → AI:

• Settings — provider, encrypted API key, base URL (for Ollama), default model, per-feature overrides.
• Usage — token totals, per-feature cost breakdown, daily buckets, drilldown to individual events.
• Features — every registered agent listed and grouped by owning package, with an on/off toggle per feature.

Each page is capability-gated on manage_ai_settings. cms-framework wires the capability; other stacks must define it themselves.

JSON API

The React and Vue starter kits consume the same data through REST endpoints so they don't have to depend on Livewire. All endpoints are Sanctum-authenticated by default and gated on the same manage_ai_settings ability.

Customise the prefix, middleware, and ability via config('artisanpack.ai.api'). Full schema in docs/reference/api-schema.json.

Drop-in React / Vue clients

Both @artisanpack-ui/react and @artisanpack-ui/vue ship an ai/ subpath that consumes these endpoints — SettingsPage, UsageDashboard, and FeatureToggles components plus a small createAiApiClient fetch wrapper.

See docs/integration/react-vue-integration.md for authentication, custom fetch wrappers, and long-running agent-output streaming via useStreamingText.

Local models (Ollama)

Ollama is a first-class provider in v1.0.0. Every downstream package that ships an agent is expected to work against Ollama in addition to a cloud provider, so a self-hosted CMS can run without ever paying per-token fees.

1. Install and start Ollama

2. Point the ai package at Ollama

Either flip the environment file:

...or select Ollama in the AI Settings admin page (Admin → Packages → AI → Settings). The admin UI prompts for a base URL instead of an API key when Ollama is chosen, and the "Test connection" button probes GET {base_url}/api/tags before saving.

3. Recommended models per feature

The following ArtisanPack UI agents have been validated end-to-end against a local Ollama daemon:

Override the recommendation per feature via config or the admin's advanced-tab per-feature model selector:

4. Local integration test

The package ships a Pest test suite that exercises ConnectionTester with a stubbed Ollama response. To run the real end-to-end suite against your daemon, set:

CI leaves ARTISANPACK_AI_OLLAMA_E2E unset — the gated group is skipped when no daemon is reachable so pipelines stay green on hosted runners.

Contributing

As an open source project, this package is open to contributions from anyone. Please read through the contributing guidelines to learn more about how you can contribute.