README

Datawell AI

AI bridge for Datawell data sources: permission-scoped tools generated from the registry.

Installation

You can install the package via Composer:

composer require datawell/ai

You may publish all of the package's resources at once:

php artisan vendor:publish --tag="datawell-ai"

Or, you may publish each resource individually:

Publishing the Configuration File

php artisan vendor:publish --tag="datawell-ai-config"

Usage

The bridge turns the sources a user may see into agent tools — generated from the published schema, never written per source (D59/D60). With laravel/ai:

use Datawell\Ai\Adapters\LaravelAi\DatawellTools;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

class Assistant implements Agent, HasTools
{
    use Promptable;

    public function __construct(public User $user) {}

    public function instructions(): string
    {
        return 'You answer questions about the workspace using the tools.';
    }

    public function tools(): iterable
    {
        return DatawellTools::for($this->user);
    }
}

What the user gets, as that user: a query_<source> tool per visible source (filters, operators, sorts, grains and enum values as real JSON-schema constraints; the source's prose as the description), one tool per visible server action, and shared lookup, values and progress tools. Hidden fields, gated actions and humanOnly actions are simply absent. Every call runs on the delegated channel; validation failures come back as tool results so the model corrects itself.

Consent rides on laravel/ai's tool approvals: an action whose confirmation policy is not never requests approval per call with a reason a person can act on ("Decline stale on Document signatures: 37 matching rows."); once approved, the tool-call id is recorded as the approval reference in the run's audit row.

Set datawell-ai.mode to compact for a fixed tool list (list_sources, describe_source, query, act) on large registries.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

This repository is a read-only copy of the ai package, published automatically from Datawell's development repository, so changes aren't merged here directly. Issues and pull requests are still welcome: accepted changes are applied upstream and published back here.

Thank you for considering contributing to Datawell AI! Please review our contributing guide to get started.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

Datawell AI is open-sourced software licensed under the MIT license.

Chart tools

Alongside the query and action tools, the bridge publishes a chart tool per groupable source (chart_people) — or one shared chart tool in compact mode. It runs the grouped query server-side and returns a typed payload:

{ "kind": "chart", "title": "…", "chart": { "type": "line", "options": {} },
  "source": "people", "request": { "groupBy": [...], "aggregates": [...] },
  "result": { "buckets": [...], "meta": {...}, "applied": {...} } }

Your chat front-end renders any tool result whose kind it recognises (the datawell/reports <ReportChart> draws this one directly) while the model, holding the buckets, narrates the takeaway. Set datawell-ai.charts to false if your interface cannot draw charts.

datawell / ai

Package info

Security

Statistics