sanvex/ecosystem

An AI-agentic ecosystem and unified API integration layer for Laravel

dev-main 2026-04-21 05:58 UTC

Requires

• php: ^8.2

MIT

README

An AI-agentic ecosystem and unified API integration layer for Laravel.

Sanvex is a powerful Laravel package designed to provide a unified, developer-friendly interface for interacting with various third-party services (GitHub, Gmail, Linear, Notion, Slack). It is built specifically to be consumed by AI Agents via dynamic tool calling, but it can also be used directly within your application code.

✨ Features

• **Unified Interface (`SanvexManager)**: Interact with any supported service using a consistent \Driver -> Resource -> Action` pattern.
• AI Tool Calling Ready: Designed from the ground up to be easily mapped to LLM function calls (e.g., OpenAI, Anthropic, Groq).
• Interactive CLI: Easily configure API keys and check driver status via built-in Artisan commands.
• Secure Credential Storage: Built-in encryption (`EncryptionService`) for storing API keys securely within your application database.
• Extensible Architecture: Easily add new custom drivers and resources.

📦 Supported Drivers

Currently, Sanvex supports the following out-of-the-box integrations:

• GitHub (Repositories, Issues, Pull Requests)
• Gmail (Emails, Threads)
• Linear (Issues, Projects)
• Notion (Pages, Databases)
• Slack (Channels, Messages, Users)

🛠️ Installation

Require the package via Composer (assuming local monorepo setup):

composer require sanvex/monorepo

Make sure the Service Providers are successfully registered in your Laravel application (e.g., inside `bootstrap/providers.php`):

\Sanvex\Core\SanvexServiceProvider::class,
\Sanvex\Mcp\McpServiceProvider::class,
\Sanvex\Drivers\GitHub\GitHubServiceProvider::class,
// ... other drivers

⚙️ Setup & Configuration

Sanvex comes with a helpful CLI module to manage your driver connections.

1. List all available drivers:

php artisan sanvex:list

2. Setup a specific driver: This command prompts you to enter required credentials (e.g., API Key, OAuth tokens) or allows them inline.

php artisan sanvex:setup github --api-key="your_api_key_here"

💻 Usage

Direct PHP Implementation

You can interact with the drivers simply using the `SanvexManager` via Dependency Injection.

use Sanvex\Core\SanvexManager;

class GithubController extends Controller
{
    public function getRepos(SanvexManager $manager)
    {
        // 1. Resolve the driver
        $github = $manager->resolveDriver("github");
        
        // 2. Access a resource module and perform an action
        $repos = $github->repositories()->list([
            "per_page" => 10
        ]);

        return response()->json($repos);
    }
}

🤖 Using with AI Agents (Tool Calling)

Sanvex really shines when bridging your application to AI models. Instead of manually writing logic for every endpoint, you can expose a generic JSON `sanvex_action` tool to your LLM.

Exposed JSON Tool Definition:

{
  "name": "sanvex_action",
  "description": "Perform an action on an integrated driver resource to fetch or manipulate data.",
  "parameters": {
    "type": "object",
    "properties": {
      "driver": { "type": "string", "description": "e.g., github, linear, notion" },
      "resource": { "type": "string", "description": "e.g., repositories, issues" },
      "action": { "type": "string", "description": "e.g., list, get, create" },
      "args": { "type": "object", "description": "Key-value arguments for the action." }
    },
    "required": ["driver", "resource", "action"]
  }
}

Dynamic Execution Pipeline:

$driverId = $instruction["driver"];      // e.g., "github"
$resource = $instruction["resource"];    // e.g., "repositories"
$action   = $instruction["action"];      // e.g., "list"
$args     = $instruction["args"] ?? [];

$driver = $manager->resolveDriver($driverId);

// Effortlessly map LLM actions directly to Sanvex features
$result = $driver->{$resource}()->{$action}($args);

return $result;