From fc31d329889df1209871beea9c1a169b70241ace Mon Sep 17 00:00:00 2001 From: Stan Date: Thu, 3 Sep 2026 13:19:54 +0500 Subject: [PATCH 1/2] docs(aimlapi): document aimlapi.com as an LLM/embedding provider cognee dispatches every completion through litellm, and litellm has shipped a first-class `aiml` provider (AIMLChatConfig, base https://api.aimlapi.com/v1) since well before the version this repo pins. So aimlapi.com already works with zero adapter code -- it was simply undiscoverable, because nothing in the repo said so. This adds the same three surfaces the OpenRouter route already has (.env.template block, CLAUDE.md snippet, integrations skill bullet), a runnable example, and the Integrations Hub card. Two facts here are not guessable and are the reason a user gives up: - `LLM_PROVIDER` must be "custom". An "aiml/" model prefix on its own raises ProviderNotDeducibleError, because cognee's provider enum is deliberately small -- the same reason OpenRouter needs "custom". - Embeddings must NOT carry the "aiml/" prefix. litellm registers no embedding route for `aiml`, so "aiml/openai/text-embedding-3-large" fails with "Unmapped LLM provider for this endpoint". The unprefixed id plus EMBEDDING_ENDPOINT pointed at aimlapi.com works, and that is what the example uses. The example uses EMBEDDING_MAX_COMPLETION_TOKENS rather than the EMBEDDING_MAX_TOKENS spelling most of test_llms.yml uses: EmbeddingConfig declares `embedding_max_completion_tokens`, and nothing reads `embedding_max_tokens`, so the shorter spelling is silently absorbed by `extra="allow"` and has no effect. Verified against the live API: the example runs end to end (remember + recall) with both the LLM and the embeddings served by aimlapi.com, and every model id named here was called through cognee's own GenericAPIAdapter, not asserted from the catalogue. --- .claude/skills/cognee-integrations/SKILL.md | 3 +- .env.template | 22 +++++ CLAUDE.md | 14 +++ catalog/entries/integrations/aimlapi.yaml | 27 ++++++ examples/guides/aimlapi_example.py | 97 +++++++++++++++++++++ 5 files changed, 162 insertions(+), 1 deletion(-) create mode 100644 catalog/entries/integrations/aimlapi.yaml create mode 100644 examples/guides/aimlapi_example.py diff --git a/.claude/skills/cognee-integrations/SKILL.md b/.claude/skills/cognee-integrations/SKILL.md index 1e6b75297a..3176afbab0 100644 --- a/.claude/skills/cognee-integrations/SKILL.md +++ b/.claude/skills/cognee-integrations/SKILL.md @@ -1,6 +1,6 @@ --- name: cognee-integrations -description: Use when the user wants to connect cognee to external services — switching LLM or embedding providers (OpenAI, Azure, Gemini, Anthropic, Ollama, OpenRouter), changing databases (Postgres, PGVector, Neo4j, Neptune, Turso), S3 storage, or the MCP server for IDE integration. +description: Use when the user wants to connect cognee to external services — switching LLM or embedding providers (OpenAI, Azure, Gemini, Anthropic, Ollama, OpenRouter, aimlapi.com), changing databases (Postgres, PGVector, Neo4j, Neptune, Turso), S3 storage, or the MCP server for IDE integration. --- # Set up cognee integrations @@ -21,6 +21,7 @@ Default is OpenAI (`LLM_API_KEY` is all you need). To switch, set - **Anthropic** (`cognee[anthropic]`): `LLM_PROVIDER=anthropic`, model e.g. `claude-3-5-sonnet-20241022`. - **Ollama, local** (`cognee[ollama]`): `LLM_PROVIDER=ollama`, `LLM_ENDPOINT=http://localhost:11434/v1`, and set the embedding block + `HUGGINGFACE_TOKENIZER` too. - **Custom / OpenRouter / vLLM**: `LLM_PROVIDER=custom` with the provider's OpenAI-compatible endpoint. +- **aimlapi.com**: `LLM_PROVIDER=custom`, `LLM_MODEL=aiml/`, `LLM_ENDPOINT=https://api.aimlapi.com/v1`. Embeddings drop the `aiml/` prefix (litellm has no aiml embedding route) and rely on `EMBEDDING_ENDPOINT` instead. - **AWS Bedrock** (`cognee[aws]`): `LLM_PROVIDER=bedrock` + AWS credentials/region. **The classic trap**: LLM and embeddings are configured independently diff --git a/.env.template b/.env.template index 500c1adf19..2c285ad649 100644 --- a/.env.template +++ b/.env.template @@ -835,6 +835,28 @@ WEB_SCRAPER_MAX_DELAY=10.0 #EMBEDDING_DIMENSIONS=3072 #EMBEDDING_MAX_COMPLETION_TOKENS=8191 +########## aimlapi.com ######################################################## +# OpenAI-compatible gateway; litellm routes it under the "aiml/" prefix, so no +# extra install is needed. LLM_PROVIDER must be "custom" -- an "aiml/" prefix on +# its own raises ProviderNotDeducibleError, exactly like "openrouter/". +# Catalogue: https://api.aimlapi.com/v1/models?include=all +# Note: litellm's own env var for this provider is AIML_API_KEY, but cognee +# never reads it -- cognee passes api_key to litellm explicitly, so the key +# must be in LLM_API_KEY (setting only AIML_API_KEY raises LLMAPIKeyNotSetError). +#LLM_API_KEY="< None: + print("\n" + "=" * 78) + print(title) + print("=" * 78) + + +async def main() -> None: + if not os.environ.get("LLM_API_KEY"): + raise SystemExit("Export LLM_API_KEY with your aimlapi.com key before running.") + + # Start from a clean slate in isolated directory + await cognee.prune.prune_data() + await cognee.prune.prune_system(metadata=True) + + banner("REMEMBER USING AIMLAPI.COM") + llm_config = get_llm_config() + print(f"Using LLM: {llm_config.llm_model}") + print(f"Using Embeddings: {os.environ.get('EMBEDDING_MODEL')}") + + await cognee.remember(SAMPLE_TEXT, dataset_name="aimlapi_demo", self_improvement=False) + print("Knowledge graph built successfully.") + + banner("RECALL") + query = "What does Cognee help developers do?" + results = await cognee.recall( + query_text=query, + query_type=SearchType.GRAPH_COMPLETION, + datasets=["aimlapi_demo"], + ) + print(f"Query: {query}") + print("Recall Results:") + print(results[0].text if results else "") + + +if __name__ == "__main__": + asyncio.run(main()) From 896ad10cce4ef3efad70ca0cc617b44e42d23624 Mon Sep 17 00:00:00 2001 From: Stan Date: Thu, 3 Sep 2026 13:21:30 +0500 Subject: [PATCH 2/2] =?UTF-8?q?chore(aimlapi):=20fork-only=20placement=20?= =?UTF-8?q?=E2=80=94=20do=20not=20send=20upstream?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Moves the aimlapi.com entry to the top of the three hand-ordered provider lists (.env.template TIER 4, CLAUDE.md's LLM Provider Configuration, and the cognee-integrations skill bullet list) and adds it first to CLAUDE.md's "Supported providers" sentence. Placement only — no content change. Kept separate so it can be dropped before an upstream PR, where provider order is the maintainers' call. Two lists are deliberately untouched because their order is machine-decided, not editorial: catalog entries are sorted by kind then id in catalog/loader.py, and the test_llms.yml jobs are an unordered GitHub Actions mapping that runs in parallel. --- .claude/skills/cognee-integrations/SKILL.md | 2 +- .env.template | 44 ++++++++++----------- CLAUDE.md | 30 +++++++------- 3 files changed, 38 insertions(+), 38 deletions(-) diff --git a/.claude/skills/cognee-integrations/SKILL.md b/.claude/skills/cognee-integrations/SKILL.md index 3176afbab0..22910c683e 100644 --- a/.claude/skills/cognee-integrations/SKILL.md +++ b/.claude/skills/cognee-integrations/SKILL.md @@ -16,12 +16,12 @@ Default is OpenAI (`LLM_API_KEY` is all you need). To switch, set `LLM_PROVIDER`, `LLM_MODEL`, `LLM_API_KEY`, and (where relevant) `LLM_ENDPOINT` / `LLM_API_VERSION`: +- **aimlapi.com**: `LLM_PROVIDER=custom`, `LLM_MODEL=aiml/`, `LLM_ENDPOINT=https://api.aimlapi.com/v1`. Embeddings drop the `aiml/` prefix (litellm has no aiml embedding route) and rely on `EMBEDDING_ENDPOINT` instead. - **Azure OpenAI**: `LLM_PROVIDER=azure`, `LLM_MODEL=azure/gpt-4o-mini`, endpoint + api version required. - **Gemini** (no extra needed): `LLM_PROVIDER=gemini`, `LLM_MODEL=gemini/gemini-2.0-flash-exp`. - **Anthropic** (`cognee[anthropic]`): `LLM_PROVIDER=anthropic`, model e.g. `claude-3-5-sonnet-20241022`. - **Ollama, local** (`cognee[ollama]`): `LLM_PROVIDER=ollama`, `LLM_ENDPOINT=http://localhost:11434/v1`, and set the embedding block + `HUGGINGFACE_TOKENIZER` too. - **Custom / OpenRouter / vLLM**: `LLM_PROVIDER=custom` with the provider's OpenAI-compatible endpoint. -- **aimlapi.com**: `LLM_PROVIDER=custom`, `LLM_MODEL=aiml/`, `LLM_ENDPOINT=https://api.aimlapi.com/v1`. Embeddings drop the `aiml/` prefix (litellm has no aiml embedding route) and rely on `EMBEDDING_ENDPOINT` instead. - **AWS Bedrock** (`cognee[aws]`): `LLM_PROVIDER=bedrock` + AWS credentials/region. **The classic trap**: LLM and embeddings are configured independently diff --git a/.env.template b/.env.template index 2c285ad649..3cbcf524f7 100644 --- a/.env.template +++ b/.env.template @@ -781,6 +781,28 @@ WEB_SCRAPER_MAX_DELAY=10.0 # Uncomment + fill values to switch providers. ############################################################################### +########## aimlapi.com ######################################################## +# OpenAI-compatible gateway; litellm routes it under the "aiml/" prefix, so no +# extra install is needed. LLM_PROVIDER must be "custom" -- an "aiml/" prefix on +# its own raises ProviderNotDeducibleError, exactly like "openrouter/". +# Catalogue: https://api.aimlapi.com/v1/models?include=all +# Note: litellm's own env var for this provider is AIML_API_KEY, but cognee +# never reads it -- cognee passes api_key to litellm explicitly, so the key +# must be in LLM_API_KEY (setting only AIML_API_KEY raises LLMAPIKeyNotSetError). +#LLM_API_KEY="<