PHPackages                             artisanpack-ui/ai - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. artisanpack-ui/ai

ActiveLibrary[Utility & Helpers](/categories/utility)

artisanpack-ui/ai
=================

Shared AI foundation for the ArtisanPack UI ecosystem, built on top of laravel/ai.

1.1.0(1mo ago)01.5k↓71.1%10MITPHP ^8.3

Since Jul 6Compare

[ Source](https://github.com/ArtisanPack-UI/ai)[ Packagist](https://packagist.org/packages/artisanpack-ui/ai)[ RSS](/packages/artisanpack-ui-ai/feed)WikiDiscussions Synced 1w ago

READMEChangelog (1)Dependencies (25)Versions (4)Used By (10)

ArtisanPack UI AI
=================

[](#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`](https://github.com/laravel/ai).

See the [AI RFC](https://github.com/ArtisanPack-UI/.github/discussions/8) for design context and the roadmap for downstream feature work.

What this package gives you
---------------------------

[](#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.
- **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](docs/reference/api-schema.json)).
- **Ollama support** — every shipped agent works against a self-hosted local model, not just the cloud providers.

Installation
------------

[](#installation)

```
composer require artisanpack-ui/ai
php artisan migrate
```

Publish the config if you want to customise defaults:

```
php artisan vendor:publish --tag=artisanpack-package-config
```

Quick start
-----------

[](#quick-start)

Access the shared foundation via the facade or helper:

```
use ArtisanPackUI\Ai\Facades\Ai;

Ai::/* ... */;

// or
ai()->/* ... */;
```

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

```
use ArtisanPackUI\Seo\Agents\MetaDescriptionAgent;

$suggestion = MetaDescriptionAgent::for( [
    'title' => $post->title,
    'body'  => $post->summary_or_body,
] )->run();

$post->update( [ 'meta_description' => $suggestion['meta_description'] ] );
```

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
-------------

[](#documentation)

Start at [docs/home.md](docs/home.md) for the full documentation index. Direct links:

- **[Getting Started](docs/getting-started.md)** — install, publish config, and run your first agent.
- **[Authoring agents](docs/guide/authoring-agents.md)** — how a downstream package adds a new AI capability, worked through with `MetaDescriptionAgent` as the running example.
- **[Built-in agents](docs/reference/built-in-agents.md)** — the cross-cutting agents shipped in this package itself (`AltTextGenerationAgent`, `ContentRewriteAgent`, `SummarizationAgent`) — inputs, output schemas, and consumer notes.
- **[Bring your own key (BYOK)](docs/guide/byok.md)** — env-mode vs. CMS-mode setup, provider-specific notes for Anthropic, OpenAI, Gemini, Groq, and Ollama.
- **[Overriding](docs/guide/overriding.md)** — container binding and config override patterns for replacing a shipped agent with your own subclass.
- **[React and Vue integration](docs/integration/react-vue-integration.md)** — authentication, base URLs, and streaming for JavaScript clients.
- **[JSON API schema](docs/reference/api-schema.json)** — OpenAPI 3.1 schema for the REST endpoints that back the React and Vue admin surfaces.

Admin surfaces
--------------

[](#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
--------

[](#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.

MethodPathPurposeGET`/api/artisanpack-ai/settings`Read current settings (no plaintext key)PUT`/api/artisanpack-ai/settings`Update credentials + overridesGET`/api/artisanpack-ai/features`List registered featuresPOST`/api/artisanpack-ai/features/{key}/toggle`Enable or disable a featureGET`/api/artisanpack-ai/usage?from=…&to=…`Aggregations for the dashboardPOST`/api/artisanpack-ai/test-connection`Probe the provider without savingCustomise the prefix, middleware, and ability via `config('artisanpack.ai.api')`. Full schema in [docs/reference/api-schema.json](docs/reference/api-schema.json).

### Drop-in React / Vue clients

[](#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.

```
// React
import { createAiApiClient, SettingsPage, UsageDashboard, FeatureToggles } from '@artisanpack-ui/react/ai';

const client = createAiApiClient({
  baseUrl: '/api/artisanpack-ai',
  headers: { 'X-CSRF-TOKEN': csrfToken },
});

```

```

import { createAiApiClient, SettingsPage, UsageDashboard, FeatureToggles } from '@artisanpack-ui/vue/ai';

const client = createAiApiClient({
  baseUrl: '/api/artisanpack-ai',
  headers: { 'X-CSRF-TOKEN': csrfToken },
});

```

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

Local models (Ollama)
---------------------

[](#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

[](#1-install-and-start-ollama)

```
# macOS
brew install ollama
ollama serve                     # starts the daemon on http://127.0.0.1:11434

# Pull a model. Recommendations by workload:
ollama pull llama3.2:1b          # tiny / fast: alt-text, short summaries
ollama pull llama3.2:3b          # balanced default for most agents
ollama pull qwen2.5:7b           # smarter, still comfortable on a laptop
ollama pull llama3.1:70b         # cloud-class quality if you have the RAM
```

### 2. Point the ai package at Ollama

[](#2-point-the-ai-package-at-ollama)

Either flip the environment file:

```
ARTISANPACK_AI_PROVIDER=ollama
ARTISANPACK_AI_BASE_URL=http://127.0.0.1:11434
ARTISANPACK_AI_DEFAULT_MODEL=llama3.2:3b
# No API key required for local Ollama.
```

...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

[](#3-recommended-models-per-feature)

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

Agent (feature key)Ollama modelNotes`seo.suggest_meta_description``llama3.2:3b`~5s per suggestion on an M1; identical schema to Anthropic.`media.generate_alt_text``llama3.2:1b`Vision-free path — pass the filename + caption context.`cms.summarize_content``qwen2.5:7b`Higher token budget benefits from the sharper model.Override the recommendation per feature via config or the admin's advanced-tab per-feature model selector:

```
// config/artisanpack/ai.php
'features' => [
    'seo.suggest_meta_description' => [
        'model' => 'qwen2.5:7b',       // pin a smarter model
    ],
],
```

### 4. Local integration test

[](#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:

```
ARTISANPACK_AI_OLLAMA_E2E=1 \
ARTISANPACK_AI_BASE_URL=http://127.0.0.1:11434 \
./vendor/bin/pest --group=ollama-e2e
```

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
------------

[](#contributing)

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

###  Health Score

47

—

FairBetter than 93% of packages

Maintenance93

Actively maintained with recent releases

Popularity21

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~14 days

Total

2

Last Release

33d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/ba2a2c40c9a93470595cd10701d2291434f3a7db61862d9700a9e69e31608c6c?d=identicon)[JacobMartellaWebDesign](/maintainers/JacobMartellaWebDesign)

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/artisanpack-ui-ai/health.svg)

```
[![Health](https://phpackages.com/badges/artisanpack-ui-ai/health.svg)](https://phpackages.com/packages/artisanpack-ui-ai)
```

###  Alternatives

[webcrafts-studio/lens-for-laravel

A local-first WCAG accessibility auditor for Laravel with axe-core, source mapping, CI workflows, and optional AI fixes.

464.2k](/packages/webcrafts-studio-lens-for-laravel)[forjedio/inertia-table

Backend-driven dynamic tables for Laravel + Inertia.js

272.0k](/packages/forjedio-inertia-table)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)