{"id":50697969,"url":"https://github.com/hacklabr/ai-assistant","last_synced_at":"2026-06-09T07:35:36.243Z","repository":{"id":357439128,"uuid":"1226098935","full_name":"hacklabr/ai-assistant","owner":"hacklabr","description":"An embeddable AI assistant framework for PHP built on top of [Neuron AI](https://neuron-ai.dev/)","archived":false,"fork":false,"pushed_at":"2026-05-12T19:14:16.000Z","size":206,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T20:36:19.922Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hacklabr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-01T01:15:06.000Z","updated_at":"2026-05-12T19:13:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hacklabr/ai-assistant","commit_stats":null,"previous_names":["hacklabr/ai-assistant"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/hacklabr/ai-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hacklabr%2Fai-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hacklabr%2Fai-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hacklabr%2Fai-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hacklabr%2Fai-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hacklabr","download_url":"https://codeload.github.com/hacklabr/ai-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hacklabr%2Fai-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34096952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-09T07:35:35.313Z","updated_at":"2026-06-09T07:35:36.229Z","avatar_url":"https://github.com/hacklabr.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HackLab AI Assistant\n\nAn embeddable AI assistant framework for PHP built on top of [Neuron AI](https://neuron-ai.dev/). Provides advanced context management, sub-agent orchestration, skill configuration, auto-learning, and MCP integration.\n\n## Features\n\n- **Context Condensation** - 4 strategies for intelligent context reduction before delegation\n- **Sub-Agent Orchestration** - Delegate tasks to specialized agents with automatically condensed context\n- **Skill System** - Configure reusable instruction modules via Markdown files with YAML frontmatter\n- **File Reading** - Built-in tool for reading PDF, DOCX, TXT, CSV, Markdown, and more\n- **Auto-Learning** - Record tool patterns, collect bugs, and get intelligent suggestions (with anti-poisoning guardrails)\n- **User Memory** - Per-user persistent memories scoped by backend-provided user ID\n- **MCP Integration** - Native support for stdio, SSE, and HTTP transports via Neuron's MCP connector\n- **Security First** - Encrypted config, sensitive data redaction, MCP command allowlist, PSR-3 logging\n- **Structured Output** - Typed PHP objects with validation via Neuron's `#[SchemaProperty]` system\n\n## Requirements\n\n- PHP 8.2+\n- [Neuron AI](https://neuron-ai.dev/) ^3.0\n\n## Installation\n\n```bash\ncomposer require hacklab/ai-assistant\n```\n\n## Quick Start\n\n```php\nuse HackLab\\AIAssistant\\Assistant;\nuse HackLab\\AIAssistant\\AssistantConfig;\nuse HackLab\\AIAssistant\\Persistence\\FileStorage;\nuse NeuronAI\\Chat\\Messages\\UserMessage;\nuse NeuronAI\\Providers\\Anthropic\\Anthropic;\n\n$assistant = Assistant::configure(\n    new AssistantConfig(\n        provider: new Anthropic(\n            key: 'your-api-key',\n            model: 'claude-sonnet-4',\n        ),\n        storage: new FileStorage(__DIR__ . '/storage'),\n        instructions: 'You are a helpful coding assistant.',\n    )\n);\n\n$response = $assistant-\u003echat(new UserMessage('Hello!'));\necho $response-\u003egetMessage()-\u003egetContent();\n```\n\n## Configuration\n\n### Basic Configuration\n\n```php\nuse HackLab\\AIAssistant\\AssistantConfig;\nuse HackLab\\AIAssistant\\Persistence\\FileStorage;\n\n$config = new AssistantConfig(\n    provider: $aiProvider,           // Neuron AIProviderInterface (required)\n    storage: new FileStorage('/path/to/storage'), // StorageInterface (required)\n    instructions: 'System prompt',   // Base instructions\n    contextWindow: 200000,           // Token limit (default: 200000)\n    tools: [],                       // Array of Tool classes/instances\n    subAgents: [],                   // Sub-agent configurations\n    skills: [],                      // Skill names to load\n    skillsPath: '/path/to/skills',   // Directory containing .md skill files\n    autoLearn: false,                // Enable auto-learning\n    autoDelegate: true,              // Enable auto-delegation to sub-agents\n    requireLearningCheck: true,      // Mandatory learning check before using tools\n    userId: $currentUser-\u003egetId(),   // Backend-provided user ID (for user memory)\n    logger: $psr3Logger,             // PSR-3 logger (optional)\n    requestTimeout: 120.0,           // HTTP client timeout in seconds (null = provider default: 60s)\n    outputClass: null,               // FQCN for structured output (class with #[SchemaProperty])\n    structuredMaxRetries: 1,         // Retries on structured output validation failure\n    conversationStorage: null,        // Override storage for conversations (falls back to $storage)\n    learningStorage: null,            // Override storage for learning data (falls back to $storage)\n    userMemoryStorage: null,          // Override storage for user memories (falls back to $storage)\n);\n```\n\n### Per-Domain Storage\n\nAssign different backends for conversations, learning, and user memories:\n\n```php\nnew AssistantConfig(\n    provider: $provider,\n    storage: new FileStorage('/data/default'),\n    conversationStorage: new RedisStorage($redis),      // conversations in Redis\n    learningStorage: new FileStorage('/data/learning'),  // learning on disk\n    userMemoryStorage: new DatabaseStorage($pdo),        // memories in DB\n);\n```\n\n### Custom Storage Backends\n\nImplement `StorageInterface` for custom backends (database, Redis, etc.):\n\n```php\nuse HackLab\\AIAssistant\\Persistence\\StorageInterface;\n\nclass RedisStorage implements StorageInterface {\n    public function save(string $namespace, string $key, array $data): void { /* ... */ }\n    public function load(string $namespace, string $key): ?array { /* ... */ }\n    public function delete(string $namespace, string $key): bool { /* ... */ }\n    public function exists(string $namespace, string $key): bool { /* ... */ }\n    public function list(string $namespace, string $pattern = '*'): array { /* ... */ }\n    public function search(string $namespace, string $query, int $limit = 10): array { /* ... */ }\n    public function cleanup(string $namespace, array $criteria = []): int { /* ... */ }\n}\n\nnew AssistantConfig(\n    provider: $provider,\n    storage: new RedisStorage($redis),\n)\n```\n\n### Supported AI Providers\n\nAny Neuron AI provider can be used:\n\n```php\nuse NeuronAI\\Providers\\Anthropic\\Anthropic;\nuse NeuronAI\\Providers\\OpenAI\\OpenAI;\nuse NeuronAI\\Providers\\Gemini\\Gemini;\nuse NeuronAI\\Providers\\Ollama\\Ollama;\nuse NeuronAI\\Providers\\Deepseek\\Deepseek;\n\n// Anthropic Claude\nnew Anthropic(key: 'sk-ant-...', model: 'claude-sonnet-4');\n\n// OpenAI GPT\nnew OpenAI(key: 'sk-...', model: 'gpt-4o');\n\n// Google Gemini\nnew Gemini(key: '...', model: 'gemini-2.0-flash');\n\n// Local Ollama (no API key needed)\nnew Ollama(model: 'llama3.2');\n\n// Deepseek\nnew Deepseek(key: '...', model: 'deepseek-chat');\n```\n\n### Custom Endpoints (OpenAI-Compatible APIs)\n\nUse `OpenAILike` for any provider with an OpenAI-compatible API:\n\n```php\nuse NeuronAI\\Providers\\OpenAILike;\n\n// Z.AI Coding Plan\nnew OpenAILike(\n    baseUri: 'https://api.z.ai/api/coding/paas/v4',\n    key: 'your-zai-api-key',\n    model: 'glm-5.1',\n    parameters: [],\n    strict_response: false,\n    httpClient: null\n);\n\n// Any other OpenAI-compatible provider\nnew OpenAILike(\n    baseUri: 'https://api.custom-provider.com/v1',\n    key: 'your-key',\n    model: 'your-model',\n    parameters: [],\n    strict_response: false,\n    httpClient: null\n);\n```\n\n## Sub-Agents\n\nDelegate tasks to specialized agents with automatically condensed context:\n\n```php\nuse HackLab\\AIAssistant\\SubAgents\\SubAgentConfig;\n\n$assistant = Assistant::configure(\n    new AssistantConfig(\n        provider: new Anthropic('key', 'claude-sonnet-4'),\n        storage: new FileStorage(__DIR__ . '/storage'),\n        subAgents: [\n            'code-reviewer' =\u003e new SubAgentConfig(\n                id: 'code-reviewer',\n                provider: new OpenAI('key', 'gpt-4'),\n                instructions: 'You are an expert code reviewer...',\n                tools: [GitToolkit::class, FileSystemToolkit::class],\n                skills: ['security', 'psr12'],\n                contextStrategy: 'code-focused',\n                contextWindow: 8000,\n                mcps: [\n                    ['type' =\u003e 'stdio', 'command' =\u003e 'npx', 'args' =\u003e ['@modelcontextprotocol/server-github']],\n                ],\n            ),\n        ],\n    )\n);\n\n// Delegate to sub-agent\n$result = $assistant-\u003edelegate('code-reviewer', new UserMessage('Check for security issues'));\necho $result-\u003egetContent();\n```\n\n## Context Condensation Strategies\n\nWhen delegating to sub-agents, context is automatically condensed using one of 4 strategies:\n\n| Strategy | Description | Best For |\n|----------|-------------|----------|\n| **Truncation** | Simple token-based cutting | Emergency fallback |\n| **Summarization** | LLM-powered summarization | Long conversations |\n| **Relevance** | Keyword/pattern matching | Task-specific delegation |\n| **Hierarchical** | Summary + recent + key facts | Complex multi-turn (default) |\n\nConfigure per sub-agent:\n\n```php\nnew SubAgentConfig(\n    // ...\n    contextStrategy: 'code-focused',  // Use relevance strategy with code keywords\n)\n```\n\n## Skills\n\nSkills are reusable instruction modules stored as Markdown files with YAML frontmatter:\n\n```markdown\n---\nname: Security Auditor\ndescription: OWASP security specialist\ntools:\n  - StaticAnalysisTool\n  - DependencyCheckTool\ncontext_strategy: security-focused\n---\n\nWhen reviewing code:\n- Check for SQL injection, XSS, CSRF\n- Validate prepared statements\n- Never expose secrets\n```\n\nLoad skills from a directory:\n\n```php\nnew AssistantConfig(\n    provider: $provider,\n    storage: $storage,\n    skillsPath: __DIR__ . '/skills',\n    skills: ['security'],  // Reference by name\n)\n```\n\n## MCP Integration\n\nConnect to MCP servers via stdio, SSE, or HTTP:\n\n```php\n// stdio (local process)\n['type' =\u003e 'stdio', 'command' =\u003e 'npx', 'args' =\u003e ['@modelcontextprotocol/server-github']]\n\n// SSE (Server-Sent Events)\n['type' =\u003e 'sse', 'url' =\u003e 'http://localhost:8080/sse', 'token' =\u003e 'optional-bearer-token']\n\n// HTTP Streaming\n['type' =\u003e 'http', 'url' =\u003e 'https://api.example.com/mcp']\n```\n\n## Auto-Learning\n\nEnable to record tool usage patterns, collect bugs, and build contextual knowledge:\n\n```php\nnew AssistantConfig(\n    provider: $provider,\n    storage: new FileStorage(__DIR__ . '/storage'),\n    autoLearn: true,\n    requireLearningCheck: true,  // Default: mandatory check before using tools\n)\n```\n\n### Learning Tools\n\nWhen auto-learning is enabled, the assistant gains access to 5 contextual learning tools:\n\n| Tool | Purpose |\n|------|---------|\n| `record_learning` | Record a pattern or anti-pattern for a specific context |\n| `get_context_insights` | Retrieve recorded learnings, patterns, and known issues |\n| `record_bug` | Document a bug or error with optional workaround |\n| `find_similar_issues` | Search for known issues before attempting an approach |\n| `forget_learning` | Remove a learning entry (with anti-poisoning guardrails) |\n\n### Contextual Organization\n\nLearnings are organized by **context** (tool name, framework, domain):\n\n```php\n// Record a successful pattern\n$assistant-\u003echat(new UserMessage(\n    'record_learning(context: \"filesystem_tool\", observation: \"Always check parent dir\", worked_well: true)'\n));\n\n// Check insights before using a tool\n$assistant-\u003echat(new UserMessage(\n    'get_context_insights(context: \"database_tool\")'\n));\n```\n\n### Mandatory Learning Check\n\nWhen `requireLearningCheck: true` (default), the assistant is instructed to **consult the learning system before using any tool for the first time** in a conversation. This prevents repeated mistakes and leverages accumulated knowledge.\n\nTo disable:\n```php\nnew AssistantConfig(\n    provider: $provider,\n    storage: $storage,\n    requireLearningCheck: false,  // Skip mandatory checks\n)\n```\n\n### Learning Guardrails\n\nThe learning system has built-in protection against **knowledge base poisoning**:\n\n- The assistant **never** records learnings directly dictated by the user\n- Learnings must originate from the agent's own observations (tool results, error patterns, code analysis)\n- If the user suggests a learning, the agent evaluates it critically and only records independently verified observations\n- Instruction-like patterns such as \"never use tool X\" are detected and rejected by the `GuardsAgainstPoisoning` trait\n- Deletion requests are also guarded against bulk manipulation patterns (`forget all`, `purge`, etc.)\n\nThis ensures the learning system cannot be manipulated through social engineering.\n\n## User Memory\n\nProvide per-user persistent memories scoped by a backend-provided user ID:\n\n```php\n$assistant = Assistant::configure(\n    new AssistantConfig(\n        provider: new Anthropic('key', 'claude-sonnet-4'),\n        storage: new FileStorage(__DIR__ . '/storage'),\n        userId: $authenticatedUser-\u003egetId(),  // Backend-provided, never from user input\n    )\n);\n```\n\n### Memory Tools\n\nWhen `userId` is provided, the assistant gains 3 memory tools:\n\n| Tool | Purpose |\n|------|---------|\n| `save_memory` | Save a memory for the current user (category: preference, context, note, instruction) |\n| `recall_memories` | Search and retrieve memories for the current user |\n| `delete_memory` | Delete a specific memory by ID (ownership verified) |\n\n### Security Model\n\n- `userId` is injected by the backend via `AssistantConfig` — the LLM **cannot** change it\n- Storage is partitioned by user ID via namespace (`memories/{userId}`)\n- `delete_memory` verifies ownership before deletion\n- One user cannot access or modify another user's memories\n\n## File Reading\n\nBuilt-in tool for reading and extracting text from local documents:\n\n```php\nuse HackLab\\AIAssistant\\Tools\\FileReader\\FileReaderTool;\n\nnew AssistantConfig(\n    provider: $provider,\n    storage: $storage,\n    tools: [new FileReaderTool()],\n);\n```\n\nThe assistant gains the `read_file` tool which accepts `file_path` (required) and `max_length` (optional, default 100k chars).\n\n### Supported Formats\n\n| Format | Extension | Dependency |\n|--------|-----------|------------|\n| PDF | `.pdf` | `smalot/pdfparser` (pure PHP) |\n| Word | `.docx` | `phpoffice/phpword` (pure PHP) |\n| Plain Text | `.txt` | Native |\n| CSV | `.csv` | Native |\n| Markdown | `.md` | Native |\n| HTML | `.html`, `.htm` | Native |\n| JSON | `.json` | Native |\n| XML | `.xml` | Native |\n| RTF | `.rtf` | Native |\n\n## Structured Output\n\nReturn typed PHP objects instead of plain text. Ideal for generating application configuration, extracting data, or building JSON APIs.\n\n### Define an output class\n\n```php\nuse NeuronAI\\StructuredOutput\\SchemaProperty;\n\nclass MapLayer\n{\n    #[SchemaProperty(description: 'Layer name', required: true)]\n    public string $name;\n\n    #[SchemaProperty(description: 'Layer type: raster, vector, tile', required: true)]\n    public string $type;\n\n    #[SchemaProperty(description: 'Source URL', required: true)]\n    public string $source;\n\n    #[SchemaProperty(description: 'Default visibility', required: false)]\n    public bool $visible = true;\n}\n\nclass MapConfig\n{\n    #[SchemaProperty(description: 'Map title', required: true)]\n    public string $title;\n\n    #[SchemaProperty(description: 'Map layers', required: true, anyOf: [MapLayer::class])]\n    public array $layers;\n}\n```\n\n### Configure and use\n\n```php\n$assistant = Assistant::configure(\n    new AssistantConfig(\n        provider: new Anthropic('key', 'claude-sonnet-4'),\n        storage: new FileStorage(__DIR__ . '/storage'),\n        instructions: 'You configure interactive maps.',\n        outputClass: MapConfig::class,\n    )\n);\n\n$config = $assistant-\u003estructured(\n    new UserMessage('Street map of São Paulo with satellite overlay')\n);\n\n// Use as object\necho $config-\u003etitle;\nforeach ($config-\u003elayers as $layer) {\n    echo $layer-\u003ename;\n}\n\n// Or return as JSON to a frontend\nheader('Content-Type: application/json');\necho json_encode($config);\n```\n\n### Explicit class per call\n\n```php\n$assistant = Assistant::configure(\n    new AssistantConfig(\n        provider: $provider,\n        storage: $storage,\n        instructions: 'Extract contact info from text.',\n    )\n);\n\n$contact = $assistant-\u003estructured(\n    new UserMessage('Alice, alice@example.com, (11) 99999-0000'),\n    ContactInfo::class,\n);\n```\n\nSee [API Reference](docs/09-api-reference.md#structured-output) for full details including validation rules and nested objects.\n\n## CLI Example\n\nInteractive command-line assistant:\n\n```php\n// See examples/cli-assistant.php\nphp examples/cli-assistant.php\n```\n\n## Documentation\n\nFull architecture documentation is available in the `docs/` directory:\n\n- [Architecture Overview](docs/01-architecture-overview.md)\n- [Core Concepts](docs/02-core-concepts.md)\n- [Context Condenser](docs/03-context-condenser.md)\n- [Sub-Agent System](docs/04-subagent-system.md)\n- [Skill System](docs/05-skill-system.md)\n- [MCP Integration](docs/06-mcp-integration.md)\n- [Auto-Learning](docs/07-auto-learning.md)\n- [Persistence](docs/08-persistence.md)\n- [API Reference](docs/09-api-reference.md) (includes Structured Output)\n- [Examples](docs/10-examples.md) (includes Map Config, Data Extraction, Reports)\n- [Development Guide](docs/11-development-guide.md)\n- [Security Audit](docs/12-security-audit.md)\n\n## Testing\n\n```bash\nvendor/bin/phpunit\n```\n\n## License\n\nBSD 3-Clause License\n\n## Contributing\n\nContributions are welcome! Please ensure:\n- PHP 8.2+ with `declare(strict_types=1)`\n- PSR-12 coding standards\n- Tests for new features\n- All documentation in English\n\n## Credits\n\nBuilt by [HackLab](https://hacklab.com.br) on top of [Neuron AI](https://neuron-ai.dev/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhacklabr%2Fai-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhacklabr%2Fai-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhacklabr%2Fai-assistant/lists"}