### Example Queries for DateTimeAgent

Source: https://github.com/vizra-ai/vizra-adk/blob/master/examples/agents/README.md

A collection of example queries demonstrating the capabilities of the DateTimeAgent, covering current time, date calculations, timezone conversions, and date information.

```text
// Current time queries
"What time is it in New York?"
"Show me the current time in Tokyo, London, and Sydney"

// Date calculations
"How many days until December 31st?"
"How many days have passed since January 1st?"
"How many days are between March 15 and June 20?"

// Timezone conversions
"What time is 3pm EST in PST?"
"If it's 9am in London, what time is it in Singapore?"
"Convert 14:30 UTC to Eastern Time"

// Date information
"What day of the week is July 4th, 2024?"
"Is December 25th, 2024 a weekend?"
"What day of the week was January 1, 2000?"

// Formatting
"Format today's date as month/day/year"
"What's today's date in long format?"
```

--------------------------------

### Install Vizra ADK Package

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CLAUDE.md

This Artisan command installs the Vizra ADK package, which typically includes publishing configuration files and running database migrations.

```bash
php artisan vizra:install
```

--------------------------------

### PHP - LLM Structured Context Extraction Example

Source: https://github.com/vizra-ai/vizra-adk/blob/master/examples/README_SHOPPING_ASSISTANT.md

Shows an example of LLM-generated JSON output for context updates, demonstrating how the agent parses structured data for preferences and shopping goals instead of relying on regex.

```php
// The LLM intelligently structures its own output
$this->parseStructuredResponse($responseText, $context);

// JSON example from LLM:
{
  "context_update": {
    "shopping_goals": {
      "budget": 150,
      "purpose": "gifts for family"
    },
    "preferences": {
      "recipients": {
        "mom": "loves plants and gardening",
        "brother": "tech-savvy, likes gadgets"
      }
    }
  }
}
```

--------------------------------

### Start Vizra ADK Web Dashboard

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CLAUDE.md

This Artisan command starts the web-based dashboard for Vizra ADK, providing a UI for managing agents, workflows, and monitoring agent activity.

```bash
php artisan vizra:dashboard
```

--------------------------------

### Integrating Agent into a Controller

Source: https://github.com/vizra-ai/vizra-adk/blob/master/examples/agents/README.md

An example of how to use the Agent facade within an HTTP controller to handle user queries and return responses, often used for API endpoints.

```php
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Vizra\VizraADK\Facades\Agent;

class DateController extends Controller
{
    public function query(Request $request)
    {
        $question = $request->input('question');

        $response = Agent::named('datetime')
            ->ask($question)
            ->execute();

        return response()->json([
            'question' => $question,
            'answer' => $response
        ]);
    }
}
```

--------------------------------

### Install Vizra ADK and Create an Agent (Bash)

Source: https://github.com/vizra-ai/vizra-adk/blob/master/README.md

This snippet shows how to install the Vizra ADK package using Composer, publish its configuration, and create a new agent. It assumes a Laravel environment with PHP and Composer installed.

```bash
composer require vizra/vizra-adk

php artisan vizra:install

php artisan vizra:make:agent CustomerSupportAgent

php artisan vizra:chat customer_support
```

--------------------------------

### Using the Agent Facade for Queries

Source: https://github.com/vizra-ai/vizra-adk/blob/master/examples/agents/README.md

Demonstrates how to interact with registered agents using the Agent facade. Supports simple queries and conversational history via sessions.

```php
use Vizra\VizraADK\Facades\Agent;

// Simple query
$response = Agent::named('datetime')
    ->ask('What time is it in Tokyo?')
    ->execute();

// With session for conversation history
$response = Agent::named('datetime')
    ->ask('How many days until Christmas?')
    ->withSession('holiday-planning')
    ->execute();
```

--------------------------------

### Vizra ADK Artisan Commands for Installation and Management

Source: https://context7.com/vizra-ai/vizra-adk/llms.txt

This collection of Bash commands covers essential administrative tasks for the Vizra ADK. It includes commands for initial installation, creating new agents and tools, listing existing agents, interactive chat sessions, generating evaluation frameworks and custom assertions, running evaluations, and managing execution traces. These commands streamline the development and operational workflow.

```bash
# Installation
php artisan vizra:install

# Agent Management
php artisan vizra:make:agent CustomerSupportAgent
php artisan vizra:make:tool OrderLookupTool
php artisan vizra:agents  # List all discovered agents
php artisan vizra:chat customer_support  # Interactive chat

# Evaluation
php artisan vizra:make:eval SupportQualityEval
php artisan vizra:make:assertion CustomAssertion
php artisan vizra:eval:run CustomerSupportEvaluation

# Tracing
php artisan vizra:trace {traceId}
php artisan vizra:trace:cleanup --days=7

```

--------------------------------

### Configure Environment Variables (Bash)

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CONTRIBUTING.md

Copies the environment example file and sets up necessary API keys for testing within the development environment.

```bash
# Copy .env.example if it exists
cp .env.example .env

# Set up your API keys for testing
OPENAI_API_KEY=your_key
ANTHROPIC_API_KEY=your_key
GEMINI_API_KEY=your_key
```

--------------------------------

### Install Vizra ADK Dependencies (Bash)

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CONTRIBUTING.md

Commands to clone the repository, install Composer dependencies, and optionally set up a local Laravel application with Vizra ADK for development.

```bash
git clone https://github.com/YOUR_USERNAME/vizra-adk.git
cd vizra-adk

git remote add upstream https://github.com/vizra-ai/vizra-adk.git

composer install

composer create-project laravel/laravel test-app
cd test-app
composer require vizra/vizra-adk:@dev --prefer-source
```

--------------------------------

### Bug Report Code Example

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CONTRIBUTING.md

A placeholder for providing a minimal code example to reproduce a bug. This helps developers quickly understand and debug issues.

```php
// Minimal code to reproduce
```

--------------------------------

### PHP PSR-12 Example Agent Class

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CONTRIBUTING.md

An example of a PHP class adhering to PSR-12 standards, demonstrating agent implementation with properties, methods, and type hints.

```php
<?php

namespace Vizra\VizraADK\Agents;

use Vizra\VizraADK\Contracts\AgentInterface;

/**
 * Class description
 */
class ExampleAgent extends BaseLlmAgent
{
    /**
     * Agent configuration
     */
    protected string $name = 'example_agent';
    protected string $description = 'Clear, concise description';
    protected string $model = 'gpt-4o';
    
    /**
     * Method description
     *
     * @param array $input
     * @return array
     */
    public function process(array $input): array
    {
        // Implementation
        return $result;
    }
}
```

--------------------------------

### Directly Running an Agent

Source: https://github.com/vizra-ai/vizra-adk/blob/master/examples/agents/README.md

Shows how to execute an agent directly using its class. This method bypasses the facade and is useful for specific agent calls.

```php
use Vizra\VizraADK\Examples\agents\DateTimeAgent;

$response = DateTimeAgent::run('Convert 3pm EST to London time')
    ->execute();
```

--------------------------------

### PHP Unit Test Example

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CONTRIBUTING.md

A basic PHP unit test using Pest, demonstrating how to instantiate an agent and assert its behavior with input processing.

```php
<?php

use Vizra\VizraADK\Agents\ExampleAgent;

it('processes input correctly', function () {
    $agent = new ExampleAgent();
    
    $result = $agent->process(['input' => 'test']);
    
    expect($result)->toBeArray()
        ->toHaveKey('output');
});

test('agent handles errors gracefully', function () {
    // Test error handling
});
```

--------------------------------

### Define a Basic LLM Agent (PHP)

Source: https://github.com/vizra-ai/vizra-adk/blob/master/README.md

This PHP code defines a customer support agent using Vizra ADK's `BaseLlmAgent`. It specifies the agent's name, description, instructions, AI model, and associated tools. Agents are auto-discovered, eliminating the need for explicit registration. The example shows how to run the agent with user context.

```php
<?php

use Vizra\VizraADK\Agents\BaseLlmAgent;
use Vizra\VizraADK\Facades\Agent;

// Define your agent
class CustomerSupportAgent extends BaseLlmAgent
{
    protected string $name = 'customer_support';
    protected string $description = 'Helps customers with inquiries';
    protected string $instructions = 'You are a helpful customer support assistant.';
    protected string $model = 'gpt-4o';

    protected array $tools = [
        OrderLookupTool::class,
        RefundProcessorTool::class,
    ];
}

// That's it! No registration needed - agents are auto-discovered

// Use your agent immediately
$response = CustomerSupportAgent::run('I need help with my order')
    ->forUser($user)
    ->go();
```

--------------------------------

### PHP - Manage Agent Context State

Source: https://github.com/vizra-ai/vizra-adk/blob/master/examples/README_SHOPPING_ASSISTANT.md

This snippet shows how to get and set state variables within the AgentContext for session persistence. It retrieves cart items, budget, preferences, and total spent, initializing them if they don't exist.

```php
$cart = $context->getState('cart', []);
$budget = $context->getState('budget');
$preferences = $context->getState('preferences', []);
$totalSpent = $context->getState('total_spent', 0);
```

```php
$context->setState('cart', $cart);
$context->setState('total_spent', $newTotal);
```

--------------------------------

### Register DateTimeAgent in AppServiceProvider

Source: https://github.com/vizra-ai/vizra-adk/blob/master/examples/agents/README.md

Registers the DateTimeAgent for use within the application by extending the Vizra ADK framework. This is typically done in the application's service provider.

```php
<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Vizra\VizraADK\Facades\Agent;
use Vizra\VizraADK\Examples\agents\DateTimeAgent;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Register example agents
        Agent::build(DateTimeAgent::class)->register();
    }
}
```

--------------------------------

### PHP Vector Memory for RAG with Vizra ADK

Source: https://context7.com/vizra-ai/vizra-adk/llms.txt

This snippet demonstrates how to use Vizra ADK's vector memory for retrieval-augmented generation (RAG). It shows adding documents (individually or in batches) to vector storage and performing semantic searches to retrieve relevant context before agent execution. Command-line examples for vector operations are also included.

```php
<?php

namespace App\Agents;

use Vizra\VizraADK\Agents\BaseLlmAgent;
use Vizra\VizraADK\System\AgentContext;

class DocumentAssistantAgent extends BaseLlmAgent
{
    protected string $name = 'document_assistant';
    protected string $instructions = 'Answer questions using provided documentation.';
    protected string $model = 'gpt-4o';

    public function execute(mixed $input, AgentContext $context): mixed
    {
        // Store documents in vector memory (one-time setup)
        $this->vector()->addDocument(
            content: file_get_contents(storage_path('docs/user-guide.md')),
            metadata: ['type' => 'user_guide', 'version' => '2.0']
        );

        // Or add multiple documents
        $docs = [
            ['content' => 'Laravel is a PHP framework...', 'metadata' => ['topic' => 'laravel']],
            ['content' => 'AI agents can use tools...', 'metadata' => ['topic' => 'agents']],
        ];
        $this->vector()->addBatch($docs);

        // Search for relevant context before responding
        $searchResults = $this->vector()->search(
            query: $input,
            limit: 5,
            filter: ['type' => 'user_guide'] // Optional metadata filter
        );

        // Inject retrieved context into agent state
        $contextText = collect($searchResults)
            ->pluck('content')
            ->implode("\n\n");

        $context->setState('documentation_context', $contextText);

        // Continue with agent execution (context will be included)
        return parent::execute($input, $context);
    }

    public function getInstructionsWithMemory(AgentContext $context): string
    {
        $instructions = parent::getInstructionsWithMemory($context);

        // Add retrieved documentation to instructions
        if ($docs = $context->getState('documentation_context')) {
            $instructions .= "\n\nRELEVANT DOCUMENTATION:\n" . $docs;
        }

        return $instructions;
    }
}

// Command-line vector operations
php artisan vizra:vector:store documentation.txt --agent=document_assistant
php artisan vizra:vector:search "How do I create an agent?" --agent=document_assistant
php artisan vizra:vector:stats --agent=document_assistant

```

--------------------------------

### PHP Agent Memory Management with Vizra ADK

Source: https://context7.com/vizra-ai/vizra-adk/llms.txt

This snippet shows how to use the Vizra ADK's agent memory to store and retrieve facts, preferences, and learnings for personalized interactions. It demonstrates adding facts, preferences, and learnings, updating summaries, remembering custom events, and searching through memories. Usage examples are also provided.

```php
<?php

namespace App\Agents;

use Vizra\VizraADK\Agents\BaseLlmAgent;
use Vizra\VizraADK\System\AgentContext;

class PersonalAssistantAgent extends BaseLlmAgent
{
    protected string $name = 'personal_assistant';
    protected string $instructions = 'You are a personal assistant that remembers user preferences.';
    protected string $model = 'gpt-4o';

    public function execute(mixed $input, AgentContext $context): mixed
    {
        // Access memory
        $memory = $this->memory();

        // Store facts about the user
        $memory->addFact("User prefers morning meetings", confidence: 0.9);
        $memory->addPreference("Communication: email over calls", "work");
        $memory->addLearning("User is interested in AI and Laravel development");
        $memory->updateSummary("Tech-savvy professional who values efficiency");

        // Generic remember with custom metadata
        $memory->remember(
            "Completed onboarding on " . now()->toDateString(),
            type: 'milestone',
            metadata: ['completed_steps' => 5]
        );

        // Retrieve stored information
        $facts = $memory->getFacts(); // Collection of fact objects
        $preferences = $memory->getPreferences('work'); // Work category preferences
        $learnings = $memory->getLearnings(); // All learnings
        $summary = $memory->getSummary(); // Overall understanding

        // Search memories
        $relevant = $memory->search('meetings', limit: 5);

        // Continue with normal agent execution
        return parent::execute($input, $context);
    }
}

// Usage
$response = Agent::run('personal_assistant', 'Schedule a meeting', userId: 123);

```

--------------------------------

### Running Tests with Composer

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CONTRIBUTING.md

This snippet shows how to execute the full test suite, run tests with coverage, and enable parallel or watch modes using Composer commands.

```bash
# Full test suite
composer test

# With coverage
composer test:coverage

# Parallel execution
./vendor/bin/pest --parallel

# Watch mode (if available)
./vendor/bin/pest --watch
```

--------------------------------

### Bash - Testing the Vizra Shopping Assistant Agent

Source: https://github.com/vizra-ai/vizra-adk/blob/master/examples/README_SHOPPING_ASSISTANT.md

This command initiates the Vizra shopping assistant agent for testing purposes via the Artisan command-line interface. It allows users to interact with the agent and test its context-aware functionalities.

```bash
# Test the agent
php artisan vizra:chat shopping_assistant
```

--------------------------------

### GET /api/agent/{name}/sessions

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CLAUDE.md

Retrieves a list of all conversation sessions associated with a specific agent.

```APIDOC
## GET /api/agent/{name}/sessions

### Description
Retrieves a list of all conversation sessions associated with a specific agent.

### Method
GET

### Endpoint
`/api/agent/{name}/sessions`

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the agent whose sessions are to be retrieved.

### Response
#### Success Response (200)
- **sessions** (array) - An array of session objects, each containing session details.
  - **session_id** (string) - The unique identifier for the session.
  - **last_message** (string) - The last message in the session.
  - **timestamp** (string) - The timestamp when the session was last updated.

#### Response Example
```json
{
  "sessions": [
    {
      "session_id": "session_abc123",
      "last_message": "How can I help you today?",
      "timestamp": "2023-10-27T10:00:00Z"
    },
    {
      "session_id": "session_def456",
      "last_message": "Thanks!",
      "timestamp": "2023-10-27T09:30:00Z"
    }
  ]
}
```
```

--------------------------------

### PHP - Inject Context into LLM Prompts (beforeLlmCall)

Source: https://github.com/vizra-ai/vizra-adk/blob/master/examples/README_SHOPPING_ASSISTANT.md

Demonstrates the `beforeLlmCall` lifecycle hook, which injects the current agent context (cart, budget, preferences, total spent) into the system message of LLM prompts to ensure context-aware responses.

```php
public function beforeLlmCall(array $inputMessages, AgentContext $context): array
{
    // Build context summary with cart, budget, preferences
    $contextSummary = $this->buildContextSummary($cart, $budget, $preferences, $totalSpent);
    
    // Inject into system message
    $inputMessages[0]['content'] = $this->instructions . "\n\n" . $contextSummary;
    
    return $inputMessages;
}
```

--------------------------------

### Define and Run a Basic LLM Agent in PHP

Source: https://context7.com/vizra-ai/vizra-adk/llms.txt

This snippet demonstrates how to define a custom AI agent by extending `BaseLlmAgent` and configuring its properties such as name, description, instructions, model, and tools. It also shows how to run the agent using the `Agent::run` facade, providing a user query and session context. The agent automatically discovers tools and can be invoked directly.

```php
<?php

namespace App\Agents;

use Vizra\VizraADK\Agents\BaseLlmAgent;
use App\Tools\OrderLookupTool;
use App\Tools\RefundProcessorTool;

class CustomerSupportAgent extends BaseLlmAgent
{
    protected string $name = 'customer_support';

    protected string $description = 'Helps customers with order inquiries and refunds';

    protected string $instructions = 'You are a helpful customer support assistant. Be polite, professional, and efficient. Always verify order information before processing refunds.';

    protected string $model = 'gpt-4o';

    protected ?float $temperature = 0.7;

    protected ?int $maxTokens = 1000;

    protected array $tools = [
        OrderLookupTool::class,
        RefundProcessorTool::class,
    ];

    // Agent is auto-discovered, no registration needed
}

// Run the agent
use Vizra\VizraADK\Facades\Agent;

$response = Agent::run(
    'customer_support',
    'I need help with order #12345',
    sessionId: 'user-123-session',
    userId: 123
);

echo $response; // "I'll look that up for you..."

```

--------------------------------

### Bash: Manual Release Execution

Source: https://github.com/vizra-ai/vizra-adk/blob/master/RELEASING.md

This snippet illustrates the manual steps for executing a release by merging the release branch into 'master', tagging the release, and pushing to the remote. It's an alternative to using a release script.

```bash
git checkout master
git merge --no-ff release/0.x.x
git tag -a v0.x.x -m "Release v0.x.x"
git push origin master --tags
```

--------------------------------

### GitHub Actions Workflow for Automated Releases

Source: https://github.com/vizra-ai/vizra-adk/blob/master/RELEASING.md

This GitHub Actions workflow automates the release process by triggering on tag pushes. It checks out the code, runs tests using Composer, and creates a GitHub release with automatically generated release notes. This simplifies the release procedure and ensures consistency.

```yaml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Run tests
        run: composer test
        
      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          generate_release_notes: true
```

--------------------------------

### Bash: Tagging Alpha Pre-release Version

Source: https://github.com/vizra-ai/vizra-adk/blob/master/RELEASING.md

This snippet shows how to tag a pre-release version as an alpha build and update the version in the 'composer.json' file. This is used for initial internal testing.

```bash
# Tag as alpha
git tag -a v0.x.x-alpha.1 -m "Alpha release"

# In composer.json
"version": "0.x.x-alpha.1"
```

--------------------------------

### Manage Prompt Versions

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CLAUDE.md

This Artisan command provides functionality for managing different versions of prompts used by the AI agents, allowing for easier experimentation and version control.

```bash
php artisan vizra:prompts
```

--------------------------------

### PHP Tool Implementation for Vizra ADK

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CLAUDE.md

Defines the structure for creating custom tools within the Vizra ADK. It requires implementing the ToolInterface, which includes a `definition()` method to describe the tool's schema (name, description, parameters) and an `execute()` method to contain the tool's core logic. Dependencies include the ToolInterface and AgentContext.

```php
class MyTool implements ToolInterface
{
    public function definition(): array
    {
        return [
            'name' => 'tool_name',
            'description' => 'What this tool does',
            'parameters' => [
                'type' => 'object',
                'properties' => [...],
                'required' => [...] 
            ]
        ];
    }
    
    public function execute(array $arguments, AgentContext $context): string
    {
        // Tool logic here
        return json_encode($result);
    }
}
```

--------------------------------

### Git Commands for Tag Management

Source: https://github.com/vizra-ai/vizra-adk/blob/master/RELEASING.md

These Git commands are essential for managing release tags. 'git tag -a' creates an annotated tag for a release candidate, while 'git tag -l' lists existing tags, sorted by version number to easily identify the latest ones.

```bash
# Tagging a release candidate
git tag -a v0.x.x-rc.1 -m "Release candidate"

# View recent tags
git tag -l "v*" --sort=-v:refname | head -10
```

--------------------------------

### Vizra ADK CLI Commands for Server Management and Dashboard

Source: https://context7.com/vizra-ai/vizra-adk/llms.txt

These Artisan commands are used for managing MCP servers and accessing the Vizra ADK web dashboard for monitoring and interaction.

```bash
php artisan vizra:mcp:list
php artisan vizra:dashboard
```

--------------------------------

### Sub-Agent Delegation with PHP Agents

Source: https://context7.com/vizra-ai/vizra-adk/llms.txt

Demonstrates creating hierarchical agent systems where parent agents delegate tasks to specialized sub-agents. This uses PHP and the Vizra ADK framework. Dependencies include the Vizra ADK library. Input is agent name and query, output is the synthesized response from sub-agents.

```php
<?php

namespace App\Agents;

use Vizra\VizraADK\Agents\BaseLlmAgent;

class EmailAnalyzerAgent extends BaseLlmAgent
{
    protected string $name = 'email_analyzer';
    protected string $description = 'Analyzes email content for sentiment and topics';
    protected string $instructions = 'Analyze emails for sentiment, urgency, and key topics.';
    protected string $model = 'gpt-4o-mini';
}

class SentimentAnalyzerAgent extends BaseLlmAgent
{
    protected string $name = 'sentiment_analyzer';
    protected string $description = 'Specialized in sentiment analysis';
    protected string $instructions = 'Analyze text sentiment and return positive/negative/neutral with confidence.';
    protected string $model = 'claude-3-5-sonnet-20241022';
}

class EmailManagerAgent extends BaseLlmAgent
{
    protected string $name = 'email_manager';
    protected string $description = 'Manages email processing and routing';
    protected string $instructions = 'You coordinate email analysis. Delegate analysis tasks to specialized sub-agents.';
    protected string $model = 'gpt-4o';

    // Register sub-agents
    protected array $subAgents = [
        EmailAnalyzerAgent::class,
        SentimentAnalyzerAgent::class,
    ];

    // Delegation happens automatically via the delegate_to_sub_agent tool
    // The LLM decides when to delegate based on instructions
}

// Usage - the main agent will delegate automatically
$response = Agent::run(
    'email_manager',
    'Analyze this email: "I am extremely disappointed with your service..."'
);

// The email_manager agent will use the delegate_to_sub_agent tool:
// 1. Calls sentiment_analyzer for emotion analysis
// 2. Calls email_analyzer for content analysis
// 3. Synthesizes results and returns comprehensive response

```

--------------------------------

### Create Sequential Workflow using Workflow Facade

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CLAUDE.md

The `Workflow::sequential()` method acts as a facade for constructing a sequential workflow. It allows developers to define a series of steps or agents to be executed in a specific order.

```php
Workflow::sequential()
```

--------------------------------

### Implement a Custom Tool for Agent in PHP

Source: https://context7.com/vizra-ai/vizra-adk/llms.txt

This code defines a custom tool, `OrderLookupTool`, by implementing the `ToolInterface`. It specifies the tool's definition, including its name, description, and parameters for execution. The `execute` method handles the logic for looking up order information from a database and uses `AgentMemory` to store contextual information about the inquiry. This allows agents to interact with external systems or data.

```php
<?php

namespace App\Tools;

use Vizra\VizraADK\Contracts\ToolInterface;
use Vizra\VizraADK\System\AgentContext;
use Vizra\VizraADK\Memory\AgentMemory;
use App\Models\Order;

class OrderLookupTool implements ToolInterface
{
    public function definition(): array
    {
        return [
            'name' => 'order_lookup',
            'description' => 'Look up order information by order ID',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'order_id' => [
                        'type' => 'string',
                        'description' => 'The order ID to look up',
                    ],
                ],
                'required' => ['order_id'],
            ],
        ];
    }

    public function execute(array $arguments, AgentContext $context, AgentMemory $memory): string
    {
        try {
            $orderId = $arguments['order_id'];

            $order = Order::where('order_number', $orderId)
                ->with(['items', 'customer'])
                ->first();

            if (!$order) {
                return json_encode([
                    'success' => false,
                    'error' => "Order {$orderId} not found",
                ]);
            }

            // Remember this order for future reference
            $memory->remember(
                "User inquired about order {$orderId}",
                'order_inquiry',
                ['order_id' => $orderId, 'status' => $order->status]
            );

            return json_encode([
                'success' => true,
                'order' => [
                    'id' => $order->order_number,
                    'status' => $order->status,
                    'total' => $order->total_amount,
                    'items' => $order->items->count(),
                    'customer' => $order->customer->name,
                    'created_at' => $order->created_at->toDateString(),
                ],
            ]);

        } catch (\Exception $e) {
            return json_encode([
                'success' => false,
                'error' => 'Failed to lookup order: ' . $e->getMessage(),
            ]);
        }
    }
}

```

--------------------------------

### PHP - Extract Insights and Update Context (afterLlmResponse)

Source: https://github.com/vizra-ai/vizra-adk/blob/master/examples/README_SHOPPING_ASSISTANT.md

Illustrates the `afterLlmResponse` lifecycle hook, used to extract relevant information from the LLM's response, such as user preferences and shopping goals, and subsequently update the agent's context.

```php
public function afterLlmResponse(Response|Generator $response, AgentContext $context): mixed
{
    // Extract user preferences from conversation
    $this->extractAndStorePreferences($responseText, $context);
    
    // Update shopping goals
    $this->updateShoppingGoals($responseText, $context);
    
    return $response;
}
```

--------------------------------

### Create a Custom Tool for an Agent (PHP)

Source: https://github.com/vizra-ai/vizra-adk/blob/master/README.md

This PHP code demonstrates how to create a custom tool for a Vizra ADK agent. The `OrderLookupTool` implements the `ToolInterface`, defining its `definition` (name, description, parameters) and `execute` method. The execute method takes arguments and agent context, performing an action like looking up order information and returning a JSON string.

```php
use Vizra\VizraADK\Contracts\ToolInterface;
use Vizra\VizraADK\System\AgentContext;

class OrderLookupTool implements ToolInterface
{
    public function definition(): array
    {
        return [
            'name' => 'order_lookup',
            'description' => 'Look up order information',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'order_id' => [
                        'type' => 'string',
                        'description' => 'The order ID',
                    ],
                ],
                'required' => ['order_id'],
            ],
        ];
    }

    public function execute(array $arguments, AgentContext $context): string
    {
        $order = Order::find($arguments['order_id']);

        return json_encode([
            'status' => 'success',
            'order' => $order->toArray(),
        ]);
    }
}
```

--------------------------------

### Vizra ADK CLI Commands for Vector Memory and Prompts

Source: https://context7.com/vizra-ai/vizra-adk/llms.txt

These Artisan commands are used to interact with Vizra ADK's vector memory for storing and searching documents, managing prompt versions, and accessing server statistics.

```bash
php artisan vizra:vector:store docs.txt --agent=document_assistant
php artisan vizra:vector:search "How do I create agents?" --agent=document_assistant
php artisan vizra:vector:stats --agent=document_assistant
php artisan vizra:prompts  # Manage prompt versions
```

--------------------------------

### List MCP Servers

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CLAUDE.md

This Artisan command lists the available MCP (Model Context Protocol) servers configured for use with Vizra ADK. MCP enables external tool servers.

```bash
php artisan vizra:mcp:list
```

--------------------------------

### Create New Tool with Vizra ADK

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CLAUDE.md

This Artisan command generates a new tool class, implementing the `ToolInterface`. This allows for extending the capabilities of AI agents within the Vizra ADK framework.

```bash
php artisan vizra:make:tool MyTool
```

--------------------------------

### Streaming Responses in PHP

Source: https://context7.com/vizra-ai/vizra-adk/llms.txt

This PHP code demonstrates how to enable real-time token-by-token streaming responses from Vizra ADK agents. It shows two approaches: within a controller action using `response()->stream` and via a builder pattern that returns a Generator. Dependencies include the Vizra ADK Agent facade and Illuminate HTTP Request.

```php
<?php

use Vizra\VizraADK\Facades\Agent;
use Illuminate\Http\Request;

// Controller action with streaming
public function chat(Request $request)
{
    $agent = Agent::named('customer_support');
    $agent->setStreaming(true);

    $stream = $agent->execute(
        $request->input('message'),
        $context
    );

    return response()->stream(function() use ($stream) {
        foreach ($stream as $chunk) {
            echo "data: " . json_encode(['content' => (string)$chunk]) . "\n\n";
            ob_flush();
            flush();
        }
        echo "data: [DONE]\n\n";
    }, 200, [
        'Content-Type' => 'text/event-stream',
        'Cache-Control' => 'no-cache',
        'X-Accel-Buffering' => 'no',
    ]);
}

// Or via builder
$response = CustomerSupportAgent::run($input)
    ->forUser($user)
    ->streaming(true)
    ->go();

// Response is a Generator that yields chunks
foreach ($response as $chunk) {
    echo $chunk;
}

```

--------------------------------

### Sequential Workflow with PHP Agents

Source: https://context7.com/vizra-ai/vizra-adk/llms.txt

Defines and executes agents in a predefined order, passing results between steps using PHP and Vizra ADK. Dependencies include Vizra ADK facades and custom agent classes. Input is the workflow name and initial data, output is the final result or an error.

```php
<?php

use Vizra\VizraADK\Facades\Workflow;
use Vizra\VizraADK\Facades\Agent;
use App\Agents\DataCollectorAgent;
use App\Agents\DataProcessorAgent;
use App\Agents\ReportGeneratorAgent;

// Define a sequential workflow
$workflow = Workflow::sequential('data_pipeline')
    ->addAgent(DataCollectorAgent::class, params: ['source' => 'database'])
    ->addAgent(DataProcessorAgent::class, params: function($input, $results, $context) {
        // Dynamic params based on previous step
        return [
            'data' => $results[DataCollectorAgent::class],
            'format' => 'json',
        ];
    })
    ->addAgent(ReportGeneratorAgent::class, params: function($input, $results, $context) {
        return [
            'processed_data' => $results[DataProcessorAgent::class],
            'template' => 'monthly_summary',
        ];
    })
    ->onSuccess(function($result, $allResults) {
        logger()->info('Workflow completed', ['final_result' => $result]);
    })
    ->onFailure(function($exception, $partialResults) {
        logger()->error('Workflow failed', ['error' => $exception->getMessage()]);
    })
    ->timeout(300) // 5 minutes
    ->retryOnFailure(attempts: 2, delayMs: 1000);

// Execute the workflow
$finalResult = Agent::run('data_pipeline', input: null, sessionId: 'workflow-session-123');

// Access individual step results
$collectedData = $workflow->getStepResult(DataCollectorAgent::class);
$processedData = $workflow->getStepResult(DataProcessorAgent::class);
$allResults = $workflow->getResults();

```

--------------------------------

### Composer Commands for Version Management

Source: https://github.com/vizra-ai/vizra-adk/blob/master/RELEASING.md

These Composer commands are used for managing the version of the Vizra ADK. 'composer version' allows for manual bumping of the version number, while 'composer show' displays the current status of the package.

```bash
# Manual version bump
composer version 0.x.x

# Check package status
composer show vizra/vizra-adk
```

--------------------------------

### Vizra ADK Provider Configuration in PHP

Source: https://context7.com/vizra-ai/vizra-adk/llms.txt

This PHP configuration file defines the default AI providers, models, and API keys for Vizra ADK. It allows setting up multiple providers like OpenAI, Anthropic, and Gemini, and configuring embedding services and HTTP client settings. The configuration also includes parameters for max delegation depth and tracing.

```php
<?php

// config/vizra-adk.php

return [
    'default_provider' => env('VIZRA_DEFAULT_PROVIDER', 'openai'),
    'default_model' => env('VIZRA_DEFAULT_MODEL', 'gpt-4o'),

    'providers' => [
        'openai' => [
            'api_key' => env('OPENAI_API_KEY'),
        ],
        'anthropic' => [
            'api_key' => env('ANTHROPIC_API_KEY'),
        ],
        'gemini' => [
            'api_key' => env('GEMINI_API_KEY'),
        ],
    ],

    'embedding' => [
        'provider' => env('VIZRA_EMBEDDING_PROVIDER', 'openai'),
        'model' => env('VIZRA_EMBEDDING_MODEL', 'text-embedding-3-small'),
    ],

    'http' => [
        'timeout' => 120,
        'connect_timeout' => 30,
    ],

    'max_delegation_depth' => 5,

    'trace' => [
        'enabled' => true,
        'retention_days' => 30,
    ],
];
```

--------------------------------

### Discover Agents using Agent Facade

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CLAUDE.md

The `Agent::discover()` method is a facade that facilitates the discovery of available agents within the Vizra ADK. It helps in identifying and listing agents registered in the system.

```php
Agent::discover()
```

--------------------------------

### Streaming Responses

Source: https://context7.com/vizra-ai/vizra-adk/llms.txt

Enable real-time token-by-token streaming for responsive user experiences. Supports both controller actions and builder patterns.

```APIDOC
## Streaming Responses

### Description
Enable real-time token-by-token streaming for responsive UX.

### Method
Not Applicable (PHP SDK / Controller Action)

### Endpoint
Not Applicable (PHP SDK / Controller Action)

### Parameters
Not Applicable (PHP SDK / Controller Action)

### Request Example
```php
<?php

use Vizra\VizraADK\Facades\Agent;
use Illuminate\Http\Request;

// Controller action with streaming
public function chat(Request $request)
{
    $agent = Agent::named('customer_support');
    $agent->setStreaming(true);

    $stream = $agent->execute(
        $request->input('message'),
        $context
    );

    return response()->stream(function() use ($stream) {
        foreach ($stream as $chunk) {
            echo "data: " . json_encode(['content' => (string)$chunk]) . "\n\n";
            ob_flush();
            flush();
        }
        echo "data: [DONE]\n\n";
    }, 200, [
        'Content-Type' => 'text/event-stream',
        'Cache-Control' => 'no-cache',
        'X-Accel-Buffering' => 'no',
    ]);
}

// Or via builder
$response = CustomerSupportAgent::run($input)
    ->forUser($user)
    ->streaming(true)
    ->go();

// Response is a Generator that yields chunks
foreach ($response as $chunk) {
    echo $chunk;
}
```

### Response
#### Success Response (200)
Stream of data chunks in Server-Sent Events format.

#### Response Example
```
data: {"content": "I'd "}

data: {"content": "be "}

data: {"content": "happy "}

data: {"content": "to "}

data: {"content": "help..."}

data: [DONE]

```
```

--------------------------------

### POST /api/v1/chat/completions

Source: https://context7.com/vizra-ai/vizra-adk/llms.txt

An OpenAI-compatible endpoint for chat completions. Allows integration with existing OpenAI tooling.

```APIDOC
## POST /api/v1/chat/completions

### Description
OpenAI-compatible Chat Completions endpoint.

### Method
POST

### Endpoint
`/api/v1/chat/completions`

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication (e.g., `Bearer your-api-key`).

#### Request Body
- **model** (string) - Required - The name of the agent to use for completion.
- **messages** (array) - Required - An array of message objects, with `role` and `content`.
  - **role** (string) - Role of the message sender (e.g., "user", "assistant").
  - **content** (string) - The text content of the message.
- **temperature** (number) - Optional - Controls randomness (0.0 to 2.0).
- **max_tokens** (integer) - Optional - Maximum number of tokens to generate.
- **stream** (boolean) - Optional - Whether to stream the response.

### Request Example
```bash
curl -X POST http://localhost/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{ 
    "model": "customer_support",
    "messages": [
      {"role": "user", "content": "Help me with my order"}
    ],
    "temperature": 0.7,
    "max_tokens": 500,
    "stream": false
  }'
```

### Response
#### Success Response (200)
Follows OpenAI's chat completion response format.
- **id** (string) - Unique identifier for the completion.
- **object** (string) - Type of object (e.g., "chat.completion").
- **created** (integer) - Timestamp of creation.
- **model** (string) - The model used for the completion.
- **choices** (array) - Array of completion choices.
  - **index** (integer) - Index of the choice.
  - **message** (object) - The message object from the assistant.
    - **role** (string) - Role of the message sender ("assistant").
    - **content** (string) - The generated content.
  - **finish_reason** (string) - The reason the model stopped generating.

#### Response Example
```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "customer_support",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "I'd be happy to help..."},
    "finish_reason": "stop"
  }]
}
```
```

--------------------------------

### Dynamically Switching AI Providers in Vizra ADK (PHP)

Source: https://context7.com/vizra-ai/vizra-adk/llms.txt

This PHP code snippet demonstrates how to dynamically switch the AI provider, model, temperature, and max tokens for a specific agent instance within Vizra ADK. This allows for flexible agent configuration at runtime.

```php
// Switch providers dynamically
$agent = Agent::named('customer_support');
$agent->setProvider('anthropic');
$agent->setModel('claude-3-5-sonnet-20241022');
$agent->setTemperature(0.8);
$agent->setMaxTokens(2000);
```

--------------------------------

### Bash: Create and Push Feature Branch

Source: https://github.com/vizra-ai/vizra-adk/blob/master/RELEASING.md

This snippet demonstrates how to create a new feature branch from the 'develop' branch and push it to the remote repository. It's the first step in the development phase of the release process.

```bash
git checkout -b feature/new-feature develop

# Work on feature
# ... make changes ...

# Push and create PR to develop
git push origin feature/new-feature
```

--------------------------------

### Bash: Using Release Script

Source: https://github.com/vizra-ai/vizra-adk/blob/master/RELEASING.md

This command executes a release script, likely automating the process of tagging and merging for patch, minor, or major releases. It's a convenient way to manage releases.

```bash
./scripts/release.sh [patch|minor|major]
```

--------------------------------

### POST /v1/chat/completions

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CLAUDE.md

An OpenAI-compatible endpoint for chat completions. This allows integration with tools and services expecting the OpenAI API format.

```APIDOC
## POST /v1/chat/completions

### Description
An OpenAI-compatible endpoint for chat completions. This allows integration with tools and services expecting the OpenAI API format.

### Method
POST

### Endpoint
`/v1/chat/completions`

### Parameters
#### Request Body
- **model** (string) - Required - The model to use for generating completions.
- **messages** (array) - Required - A list of message objects representing the conversation history.
  - **role** (string) - Required - The role of the message sender (e.g., 'system', 'user', 'assistant').
  - **content** (string) - Required - The content of the message.
- **stream** (boolean) - Optional - Whether to stream the response chunks.

### Request Example
```json
{
  "model": "gpt-4",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Who won the world series in 2020?"}
  ],
  "stream": false
}
```

### Response
#### Success Response (200)
- **choices** (array) - An array of completion choices.
  - **message** (object) - The generated message.
    - **role** (string) - The role of the assistant.
    - **content** (string) - The content of the assistant's reply.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "The Los Angeles Dodgers won the World Series in 2020."
      }
    }
  ]
}
```
```

--------------------------------

### Vizra ADK Agent Definition Pattern

Source: https://github.com/vizra-ai/vizra-adk/blob/master/CLAUDE.md

Illustrates the typical structure for defining a custom AI agent in Vizra ADK. It includes properties for name, description, instructions, model selection, and associated tools.

```php
class MyAgent extends BaseLlmAgent
{
    protected string $name = 'my_agent';
    protected string $description = 'Agent purpose';
    protected string $instructions = 'Detailed instructions';
    protected string $model = 'gpt-4o';
    protected array $tools = [
        MyTool::class,
    ];
}
```