{"id":48817228,"url":"https://github.com/generoi/gds-assistant","last_synced_at":"2026-04-17T00:03:44.588Z","repository":{"id":351096129,"uuid":"1209535397","full_name":"generoi/gds-assistant","owner":"generoi","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-13T16:10:02.000Z","size":307,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T16:32:28.557Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/generoi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-04-13T14:23:08.000Z","updated_at":"2026-04-13T15:30:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/generoi/gds-assistant","commit_stats":null,"previous_names":["generoi/gds-assistant"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/generoi/gds-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/generoi%2Fgds-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/generoi%2Fgds-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/generoi%2Fgds-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/generoi%2Fgds-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/generoi","download_url":"https://codeload.github.com/generoi/gds-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/generoi%2Fgds-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31795334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T11:13:53.975Z","status":"ssl_error","status_checked_at":"2026-04-14T11:13:53.299Z","response_time":153,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-04-14T12:01:31.847Z","updated_at":"2026-04-14T12:01:32.628Z","avatar_url":"https://github.com/generoi.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GDS Assistant\n\nAI chat assistant built into the WordPress admin. Talk to it in natural language to manage your site — create pages, edit content, run audits, handle translations, and more.\n\n### What it does\n\n- **Chat with AI in your admin** — a floating chat widget on every admin page. Ask it to do things like \"create a draft campaign page\" or \"find all pages with broken links\" and it actually does them using your site's real data.\n- **Multiple AI providers** — supports Claude (Anthropic), GPT (OpenAI), Gemini (Google), Mistral, Groq, xAI, and DeepSeek. Pick the model that fits the task — cheap and fast for quick queries, powerful for complex operations. Switch mid-conversation.\n- **Skills** — save reusable prompts as skills (like macros). Create them through the chat or in WP Admin under Tools \u003e AI Skills. Invoke with `/skill-name`. Each skill can have a preferred model — e.g. use a cheap model for lookups, a smart one for content creation.\n- **Conversation history** — past chats are saved and searchable. Pick up where you left off. See how much each conversation cost.\n- **Cost tracking** — live token count and estimated cost displayed as you chat. Price indicators ($-$$$$) next to each model so you know what you're spending.\n- **Works with your content** — the assistant can list, create, update, and delete posts, pages, products, media, translations, forms, blocks, and more. It sees your actual site structure and uses real WordPress APIs.\n\nBuilt on [assistant-ui](https://www.assistant-ui.com/) for the chat UI and the [WordPress Abilities API](https://github.com/WordPress/abilities-api) for tool execution.\n\n## Requirements\n\n- PHP \u003e= 8.3\n- WordPress \u003e= 6.8\n- [generoi/gds-mcp](https://github.com/generoi/gds-mcp) (provides WordPress tools)\n- At least one AI provider API key configured\n\n## Installation\n\n```bash\ncomposer install\nnpm install\nnpm run build\nwp plugin activate gds-assistant\n```\n\n## Configuration\n\nAll configuration via environment variables and filters. No settings page.\n\n### Environment Variables\n\nSet API keys for the providers you want to use. The chat widget only loads if at least one provider is configured.\n\n#### Provider API Keys\n\nEach provider checks multiple env var names (first match wins):\n\n| Provider               | Env vars (checked in order)                                                 | Get a key                                               |\n| ---------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------- |\n| **Anthropic** (Claude) | `GDS_ASSISTANT_ANTHROPIC_KEY`, `GDS_ASSISTANT_API_KEY`, `ANTHROPIC_API_KEY` | [console.anthropic.com](https://console.anthropic.com/) |\n| **OpenAI**             | `GDS_ASSISTANT_OPENAI_KEY`, `OPENAI_API_KEY`                                | [platform.openai.com](https://platform.openai.com/)     |\n| **Google Gemini**      | `GDS_ASSISTANT_GEMINI_KEY`, `GOOGLE_AI_API_KEY`                             | [aistudio.google.com](https://aistudio.google.com/)     |\n| **Mistral**            | `GDS_ASSISTANT_MISTRAL_KEY`, `MISTRAL_API_KEY`                              | [console.mistral.ai](https://console.mistral.ai/)       |\n| **Groq**               | `GDS_ASSISTANT_GROQ_KEY`, `GROQ_API_KEY`                                    | [console.groq.com](https://console.groq.com/)           |\n| **xAI** (Grok)         | `GDS_ASSISTANT_XAI_KEY`, `XAI_API_KEY`                                      | [console.x.ai](https://console.x.ai/)                   |\n| **DeepSeek**           | `GDS_ASSISTANT_DEEPSEEK_KEY`, `DEEPSEEK_API_KEY`                            | [platform.deepseek.com](https://platform.deepseek.com/) |\n\n#### Other Settings\n\n```env\n# Optional — override the default provider (first available is used otherwise)\nGDS_ASSISTANT_DEFAULT_PROVIDER=anthropic\n\n# Optional — default max output tokens (default: 4096)\nGDS_ASSISTANT_MAX_TOKENS=4096\n```\n\n#### Example .env\n\n```env\n# Anthropic (Claude) — primary provider\nGDS_ASSISTANT_ANTHROPIC_KEY=sk-ant-api03-...\n\n# OpenAI — secondary provider\nGDS_ASSISTANT_OPENAI_KEY=sk-proj-...\n\n# Gemini — cheap option for quick queries\nGDS_ASSISTANT_GEMINI_KEY=AIza...\n```\n\n### Available Models\n\nModels are grouped by provider in the chat widget dropdown. Only providers with configured API keys appear.\n\n| Provider      | Model Key                 | Label          | Notes                          |\n| ------------- | ------------------------- | -------------- | ------------------------------ |\n| **Anthropic** | `anthropic:haiku`         | Haiku          | Fast, cheap                    |\n|               | `anthropic:sonnet`        | Sonnet         | Best balance (default)         |\n|               | `anthropic:opus`          | Opus           | Most capable                   |\n|               | `anthropic:haiku-advisor` | Haiku+Advisor  | Haiku executor + Opus advisor  |\n|               | `anthropic:advisor`       | Sonnet+Advisor | Sonnet executor + Opus advisor |\n| **OpenAI**    | `openai:gpt-4.1-mini`     | GPT-4.1 Mini   | Fast, affordable               |\n|               | `openai:gpt-4.1`          | GPT-4.1        | Strong tool use                |\n|               | `openai:o4-mini`          | o4 Mini        | Reasoning model                |\n| **Gemini**    | `gemini:gemini-flash`     | Flash 2.5      | Very cheap                     |\n|               | `gemini:gemini-pro`       | Pro 2.5        | Near-Opus quality              |\n| **Mistral**   | `mistral:mistral-large`   | Large          | EU-hosted                      |\n| **Groq**      | `groq:llama-scout`        | Llama Scout    | Ultra-fast inference           |\n|               | `groq:llama-maverick`     | Llama Maverick | Larger Llama model             |\n| **xAI**       | `xai:grok-3`              | Grok 3         | Full model                     |\n|               | `xai:grok-3-fast`         | Grok 3 Fast    | Faster variant                 |\n| **DeepSeek**  | `deepseek:deepseek-chat`  | DeepSeek Chat  | Cheapest option                |\n\n### Filters\n\n| Filter                             | Default                               | Description                                 |\n| ---------------------------------- | ------------------------------------- | ------------------------------------------- |\n| `gds-assistant/capability`         | `edit_posts`                          | Minimum user capability to access the chat  |\n| `gds-assistant/retention_days`     | `30`                                  | Days before conversations are auto-deleted  |\n| `gds-assistant/max_iterations`     | `25`                                  | Maximum agentic loop iterations per message |\n| `gds-assistant/rate_limit`         | `['requests' =\u003e 20, 'window' =\u003e 300]` | Per-user rate limit                         |\n| `gds-assistant/system_prompt`      | (auto-generated)                      | Customize the system prompt                 |\n| `gds-assistant/tools`              | (all registered)                      | Filter available tools                      |\n| `gds-assistant/provider`           | (from registry)                       | Override the LLM provider instance          |\n| `gds-assistant/register_providers` | —                                     | Action to register custom providers         |\n| `gds-assistant/register_tools`     | —                                     | Action to register custom tool providers    |\n\n## Architecture\n\n### LLM Providers\n\nThree provider implementations ship out of the box:\n\n- **AnthropicProvider** — Claude models with streaming + advisor tool support\n- **OpenAiCompatibleProvider** — Covers OpenAI, Mistral, Groq, xAI, and DeepSeek (same API format, different base URLs)\n- **GeminiProvider** — Google Gemini with function calling\n\nThe `ProviderRegistry` auto-discovers available providers from env vars and exposes them to the frontend model selector. Add custom providers via the `gds-assistant/register_providers` action.\n\n### Tool Bridge\n\nTools are sourced from WordPress Abilities API via `AbilitiesToolProvider`. The `ToolProviderInterface` allows registering additional tool sources. Hook into `gds-assistant/register_tools` to add providers.\n\n### Streaming\n\nThe chat endpoint (`POST /wp-json/gds-assistant/v1/chat`) streams Server-Sent Events (SSE). The entire agentic loop runs server-side in a single SSE connection. No WebSockets required.\n\n### Storage\n\n- **Conversations**: `{prefix}_gds_assistant_conversations` — messages, token usage, per-user\n- **Audit log**: `{prefix}_gds_assistant_audit_log` — every tool execution with input/result\n- **Cleanup**: Daily WP-Cron prunes old records based on `gds-assistant/retention_days`\n\n### Skills\n\nReusable prompt templates stored as a custom post type (`assistant_skill`). Invoke via `/slug` in the chat. Manage in WP Admin under Tools \u003e AI Skills, or ask the assistant to create them.\n\n## Development\n\n```bash\ncomposer install\nnpm install\nnpm run build          # Production build\nnpm run start          # Watch mode\ncomposer lint          # Check PHP code style\ncomposer lint:fix      # Fix PHP code style\nnpm run lint           # Check JS/CSS code style\nnpm run lint:fix       # Fix JS/CSS code style\n```\n\n## Testing\n\n```bash\nnpx @wordpress/env start\ncomposer test:wp-env\nnpx @wordpress/env stop\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeneroi%2Fgds-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeneroi%2Fgds-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeneroi%2Fgds-assistant/lists"}