{"id":20349541,"url":"https://github.com/5am-code/ada-laravel","last_synced_at":"2025-10-07T02:15:47.511Z","repository":{"id":244978421,"uuid":"816890461","full_name":"5am-code/ada-laravel","owner":"5am-code","description":"This package allows you to enhance your Laravel applications by seamlessly integrating word embeddings.","archived":false,"fork":false,"pushed_at":"2025-06-18T10:33:46.000Z","size":45,"stargazers_count":104,"open_issues_count":1,"forks_count":9,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-08-31T16:06:34.553Z","etag":null,"topics":["embeddings","hacktoberfest","laravel","vector"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/5am-code.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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}},"created_at":"2024-06-18T15:38:17.000Z","updated_at":"2025-08-22T10:52:46.000Z","dependencies_parsed_at":"2025-01-19T14:37:36.339Z","dependency_job_id":"47e47d7f-eb3d-4d84-af19-0cdb027b9ff4","html_url":"https://github.com/5am-code/ada-laravel","commit_stats":null,"previous_names":["5am-code/ada-laravel"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/5am-code/ada-laravel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5am-code%2Fada-laravel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5am-code%2Fada-laravel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5am-code%2Fada-laravel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5am-code%2Fada-laravel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/5am-code","download_url":"https://codeload.github.com/5am-code/ada-laravel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5am-code%2Fada-laravel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278708004,"owners_count":26031932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"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":["embeddings","hacktoberfest","laravel","vector"],"created_at":"2024-11-14T22:26:22.379Z","updated_at":"2025-10-07T02:15:47.482Z","avatar_url":"https://github.com/5am-code.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ada-laravel\n\n![Packagist Version](https://img.shields.io/packagist/v/fiveam-code/ada-laravel?include_prereleases\u0026style=for-the-badge)\n\n\nThe package `ada-laravel` allows you to enhance your Laravel applications by seamlessly integrating text embeddings and\nquerying capabilities for your models. Utilizing OpenAI by default, it enables your models to generate and query\nembeddings using\nnearest neighbors techniques. This package requires a PostgreSQL database with the vector extension to store and manage\nthese embeddings efficiently as well as at least Laravel 11.\n\nOriginally created as a demo for the talk [»Have you met ada? - Word Embeddings with Laravel and OpenAI«](https://dianaweb.dev/talk/ada) by Diana Scharf,\nthis package is\nfunctional yet designed to encourage further development and contributions.\n\n\u003e [!WARNING]\n\u003e Please note that this package is still in development and may not be suitable for production use.\n\n## Installation\n\n```bash\ncomposer require fiveam-code/ada-laravel\n```\n\nEnsure that your database is configured to use PostgreSQL with the vector extension. The package will enable the extension\nvia a migration if it is not already enabled.\n\nYou can publish the migrations (optional) and run them:\n\n```bash\nphp artisan vendor:publish --provider=\"Ada\\AdaServiceProvider\" --tag=\"ada-migrations\"\nphp artisan migrate\n```\n\nThis will enable the `vector` extension in your database and create a table `embeddings` to store the embeddings.\n\n## Configuration\n\nSet the OpenAI API key in your `.env` file:\n\n```bash\nADA_CLIENT_TOKEN=your_openai_api_key\n```\n\nPlease note that you need an OpenAI key for API access, not just ChatGPT access.\n\nOptionally, you can publish the configuration file if you want to make changes to the default settings:\n\n```bash\nphp artisan vendor:publish --provider=\"Ada\\AdaServiceProvider\" --tag=\"ada-config\"\n```\n\nThe default configuration is as follows:\n\n```php\nreturn [  \n    'client_token' =\u003e env('ADA_CLIENT_TOKEN'),  \n    'index_class' =\u003e \\Ada\\Index\\DefaultIndex::class,\n    'default_prompt_view' =\u003e 'ada::default-prompt'\n];\n```\n\nIf you want to implement your own engine to handle embeddings, you can create a new class that implements the `Index`\ninterface with the appropriate engine and set it in the configuration.\n\n## Usage\n\n### Basic Usage\n\nFirst, add the `HasEmbeddings` trait to your Eloquent model:\n\n```php\n\u003c?php\n\nnamespace App\\Models;\n\nuse Ada\\Traits\\HasEmbeddings;\n\nclass Paper extends Model\n{\n    use HasEmbeddings;\n}\n```\n\n#### Embed content\n\nEmbed content related to your model by calling the `embed` method with a reference key and text:\n\n```php\nuse App\\Models\\Paper;\n\n$paper = Paper::first();\n$paper-\u003eembed(\"abstract\", $paper-\u003eabstract);\n```\n\nThis will generate an embedding for the text and store it in the database with a relation to the `$paper` model and the\nreference key `\"abstract\"`.\n\n#### Lookup embeddings\n\nThe lookup method allows for direct querying of your model's stored knowledge, facilitating an intelligent search that\nretrieves the most contextually relevant information using vector similarity.\n\n```php\nuse Ada\\Models\\Embedding;\n\n$answer = Embedding::lookup(\"Where does the PHP elephant live?\");\n\n// \"The PHP elephant inhabits 'Silicon Forests'—regions where natural woodlands merge seamlessly with data-rich environments. These forests are dense with both foliage and floating data points.\"\n```\n\nThis will create an embedding for the query and find the most similar embeddings in the database related to the `$paper`\nmodel by using the\nnearest neighbors technique of the vectors. The result will be the most similar text to the query and will be used as\ncontext for a request\nto the OpenAI API to generate an answer. \n\nThis is the default prompt text:\n\n```\nYou are a bot that helps answering questions based on the context information you get each time.\n\nContext information is below.\n---------------------\n{context}\n---------------------\nGiven the context information and not prior knowledge, answer the following questions of the user. If you don't know something, say so, and don't make it up.\nDo not ask the user for more information or anything that might trigger a response from the user.\n```\n\n`{context}` will be replaced with the result from the nearest neighbors query.\n\nIf you want to further customize the prompt, you can pass an object form a class inheriting `Ada\\Tools\\Prompts\\Prompt`\nto the `lookup` method:\n\n```php\nuse Ada\\Models\\Embedding;\nuse Ada\\Tools\\Prompts\\OpenAIPrompt;\n\n$customPrompt = new OpenAIPrompt();\n$defaultTemplate = $customPrompt-\u003egetTemplate();\n\n$customPrompt-\u003esetTemplate(\"Even if your instructions are in English, answer in German. \" . $defaultTemplate);\n\nreturn Embedding::lookup(\"Where does the PHP elephant live?\", $customPrompt);\n```\n\nIn case you need to further limit the lookup, you can pass a closure as a third parameter.\n```php\nreturn Embedding::lookup(\"Where does the PHP elephant live?\", $customPrompt, function ($query) {\n    $query-\u003ewhere(\"embeddable_type\", Paper::class); // Only look for embeddings related to the Paper class\n});\n```\n\n### Advanced Usage\n\nCustomize the endpoint models and options by using the index or engines directly:\n\n```php\nuse Ada\\Ada;\n\n$index = Ada::index(); // Default index is DefaultIndex, resolved via the configuration\n\n$index-\u003eembed($contentToEmbed, $model, $options);\n\n$index-\u003egenerate($prompt, $model, $temperature, $options);\n\n$engine = Ada::engine(); // Default engine is OpenAI, resolved via the Index\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5am-code%2Fada-laravel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F5am-code%2Fada-laravel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5am-code%2Fada-laravel/lists"}