From 1520e2163b58e97e30070580bdf1748ca7342b1a Mon Sep 17 00:00:00 2001 From: MVS-source Date: Thu, 16 Jul 2026 17:32:11 +0200 Subject: [PATCH 1/2] docs: add Pydantic AI guide and Hermes standalone provider-plugin section - Pydantic AI: new integration guide (AI Frameworks). Type-safe agents on Eden AI via OpenAIChatModel + OpenAIProvider; house-style env var EDEN_AI_API_KEY. - Hermes: add an optional "First-class provider plugin" section documenting the standalone model-provider plugin route (native --provider eden-ai), alongside the existing custom-provider setup. Additive edit only. Non-runnable Python snippets (pydantic-ai import; Hermes internal `providers` import) are marked with {/* skip-test */} so the snippet execution CI skips them. Includes pydantic-ai icon SVG and docs.json nav entry. --- docs.json | 3 +- integration-logo/pydantic-ai-icondoc.svg | 3 + v3/integrations/hermes.mdx | 47 +++++- v3/integrations/pydantic-ai.mdx | 206 +++++++++++++++++++++++ 4 files changed, 257 insertions(+), 2 deletions(-) create mode 100644 integration-logo/pydantic-ai-icondoc.svg create mode 100644 v3/integrations/pydantic-ai.mdx diff --git a/docs.json b/docs.json index c24f4a7..dad47e1 100644 --- a/docs.json +++ b/docs.json @@ -223,7 +223,8 @@ "pages": [ "v3/integrations/openai-sdk-python", "v3/integrations/openai-sdk-typescript", - "v3/integrations/langchain" + "v3/integrations/langchain", + "v3/integrations/pydantic-ai" ] }, { diff --git a/integration-logo/pydantic-ai-icondoc.svg b/integration-logo/pydantic-ai-icondoc.svg new file mode 100644 index 0000000..95e725f --- /dev/null +++ b/integration-logo/pydantic-ai-icondoc.svg @@ -0,0 +1,3 @@ + + + diff --git a/v3/integrations/hermes.mdx b/v3/integrations/hermes.mdx index 0f9f8c5..f76e9eb 100644 --- a/v3/integrations/hermes.mdx +++ b/v3/integrations/hermes.mdx @@ -15,7 +15,7 @@ import { TechArticleSchema } from "/snippets/TechArticleSchema.mdx"; proficiencyLevel="Intermediate" keywords={["Eden AI", "AI API", "Hermes Agent", "Nous Research"]} datePublished="2026-06-19T00:00:00Z" - dateModified="2026-06-19T00:00:00Z" + dateModified="2026-07-16T00:00:00Z" /> Connect [Hermes Agent](https://hermes-agent.nousresearch.com) to Eden AI and run the self-hosted, persistent agent on 500+ models with automatic fallbacks and a single API key. @@ -123,6 +123,51 @@ Hermes can fall back to a backup model when the primary one fails. Add a second hermes fallback add ``` +## First-class provider plugin (optional) + +The setup above uses Hermes' generic `custom` provider, which is the fastest way to get running. For a **native `--provider eden-ai` experience** — so Eden AI shows up in `hermes model`, `hermes doctor`, and the setup wizard — install Eden AI as a **standalone model-provider plugin**. Drop a directory under `$HERMES_HOME/plugins/model-providers/eden-ai/`, with no changes to the Hermes repo: + + +{/* skip-test */} +```python __init__.py +from providers import register_provider +from providers.base import ProviderProfile + +eden_ai = ProviderProfile( + name="eden-ai", + aliases=("edenai",), + display_name="Eden AI", + description="Eden AI — 500+ models via one OpenAI-compatible API (EU/GDPR)", + signup_url="https://app.edenai.run", + env_vars=("EDENAI_API_KEY",), + base_url="https://api.edenai.run/v3", + auth_type="api_key", + default_aux_model="mistral/mistral-small-latest", + fallback_models=( + "anthropic/claude-sonnet-4-5", + "openai/gpt-4o", + "mistral/mistral-small-latest", + ), +) + +register_provider(eden_ai) +``` + +```yaml plugin.yaml +name: eden-ai +kind: model-provider +version: 1.0.0 +description: Eden AI — 500+ models via one OpenAI-compatible API (EU/GDPR) +author: Eden AI +``` + + +Hermes then auto-wires credential resolution, the `--provider eden-ai` flag, the `hermes model` picker (models fetched from `{base_url}/models`), and the `hermes doctor` health check. Select it with: + +```bash +hermes chat --provider eden-ai +``` + ## Troubleshooting ### `401` / `Custom token not found` diff --git a/v3/integrations/pydantic-ai.mdx b/v3/integrations/pydantic-ai.mdx new file mode 100644 index 0000000..748214a --- /dev/null +++ b/v3/integrations/pydantic-ai.mdx @@ -0,0 +1,206 @@ +--- +title: "Pydantic AI" +icon: "/integration-logo/pydantic-ai-icondoc.svg" +description: "Use Pydantic AI with Eden AI to build type-safe agents on 500+ AI models through one API." +--- + +import { TechArticleSchema } from "/snippets/TechArticleSchema.mdx"; + + + +Use Pydantic AI with Eden AI to build type-safe agents on 500+ AI models through one API. + +## Overview + +Pydantic AI is a type-safe, structured-output agent framework for Python. It works with any OpenAI-compatible endpoint through `OpenAIChatModel` + `OpenAIProvider`, so you can point it at Eden AI's V3 API and access models from OpenAI, Anthropic, Google, Cohere, Meta, and more — behind one key, with EU-based, GDPR-aligned inference. + +## Installation + + +```bash pip +pip install pydantic-ai +``` + +```bash poetry +poetry add pydantic-ai +``` + + + +## Quick Start + +Point Pydantic AI's OpenAI model at Eden AI: + + +{/* skip-test */} +```python Python +from pydantic_ai import Agent +from pydantic_ai.models.openai import OpenAIChatModel +from pydantic_ai.providers.openai import OpenAIProvider + +model = OpenAIChatModel( + "openai/gpt-4o", + provider=OpenAIProvider( + api_key="YOUR_EDEN_AI_API_KEY", # Get from https://app.edenai.run + base_url="https://api.edenai.run/v3", + ), +) + +agent = Agent(model) +result = agent.run_sync("Hello! How are you?") +print(result.output) +``` + + +## Available Models + +Access models from multiple providers using the `provider/model` format: + +**OpenAI** +- `openai/gpt-4o` +- `openai/gpt-4o-mini` +- `openai/gpt-4-turbo` + +**Anthropic** +- `anthropic/claude-sonnet-4-5` +- `anthropic/claude-opus-4-5` +- `anthropic/claude-haiku-4-5` + +**Google** +- `google/gemini-2.5-pro` +- `google/gemini-2.5-flash` + +**Mistral** +- `mistral/mistral-large-latest` +- `mistral/mistral-small-latest` + +## Structured Output + +Pydantic AI's signature feature works unchanged — define a Pydantic `output_type` and the agent returns a validated object, whichever Eden AI model you choose: + + +{/* skip-test */} +```python Python +from pydantic import BaseModel +from pydantic_ai import Agent +from pydantic_ai.models.openai import OpenAIChatModel +from pydantic_ai.providers.openai import OpenAIProvider + +class City(BaseModel): + name: str + country: str + population: int + +model = OpenAIChatModel( + "anthropic/claude-sonnet-4-5", + provider=OpenAIProvider( + api_key="YOUR_EDEN_AI_API_KEY", + base_url="https://api.edenai.run/v3", + ), +) + +agent = Agent(model, output_type=City) +result = agent.run_sync("Tell me about the capital of France.") +print(result.output) # City(name='Paris', country='France', population=...) +``` + + +## Multi-Turn Conversations + +Keep conversation history across runs with `message_history`: + + +{/* skip-test */} +```python Python +from pydantic_ai import Agent +from pydantic_ai.models.openai import OpenAIChatModel +from pydantic_ai.providers.openai import OpenAIProvider + +model = OpenAIChatModel( + "anthropic/claude-sonnet-4-5", + provider=OpenAIProvider( + api_key="YOUR_EDEN_AI_API_KEY", + base_url="https://api.edenai.run/v3", + ), +) +agent = Agent(model, system_prompt="You are a helpful assistant.") + +result = agent.run_sync("What is the capital of France?") +print(result.output) + +# Continue the conversation with prior context +result = agent.run_sync( + "What's its population?", + message_history=result.all_messages(), +) +print(result.output) +``` + + +## Error Handling + + +{/* skip-test */} +```python Python +from pydantic_ai import Agent +from pydantic_ai.models.openai import OpenAIChatModel +from pydantic_ai.providers.openai import OpenAIProvider +from pydantic_ai.exceptions import ModelHTTPError, UnexpectedModelBehavior + +model = OpenAIChatModel( + "openai/gpt-4o", + provider=OpenAIProvider( + api_key="YOUR_EDEN_AI_API_KEY", + base_url="https://api.edenai.run/v3", + ), +) +agent = Agent(model) + +try: + result = agent.run_sync("Hello!") + print(result.output) +except ModelHTTPError as e: + print(f"Model HTTP error (auth, rate limit, bad request): {e}") +except UnexpectedModelBehavior as e: + print(f"Unexpected model behavior: {e}") +``` + + +## Environment Variables + + +```bash .env +EDEN_AI_API_KEY=your_api_key_here +``` + +{/* skip-test */} +```python Python +import os +from pydantic_ai.models.openai import OpenAIChatModel +from pydantic_ai.providers.openai import OpenAIProvider + +model = OpenAIChatModel( + "openai/gpt-4o", + provider=OpenAIProvider( + api_key=os.getenv("EDEN_AI_API_KEY"), + base_url="https://api.edenai.run/v3", + ), +) +``` + + +## Next Steps + +- [Chat Completions](/v3/llms/chat-completions) - Core LLM endpoint +- [List LLM Models](/v3/llms/listing-models) - Browse available providers and models +- [OpenAI SDK (Python)](/v3/integrations/openai-sdk-python) - Direct SDK usage From 6a148e76a899c6e750d316868a1aed8d2c08e402 Mon Sep 17 00:00:00 2001 From: MVS-source Date: Thu, 16 Jul 2026 18:06:29 +0200 Subject: [PATCH 2/2] docs: use current model IDs (gpt-5.5, claude-sonnet-5/opus-4-8, mistral-small-2603) in Pydantic AI + Hermes plugin snippet --- v3/integrations/hermes.mdx | 8 ++++---- v3/integrations/pydantic-ai.mdx | 25 ++++++++++++------------- 2 files changed, 16 insertions(+), 17 deletions(-) diff --git a/v3/integrations/hermes.mdx b/v3/integrations/hermes.mdx index f76e9eb..c85783d 100644 --- a/v3/integrations/hermes.mdx +++ b/v3/integrations/hermes.mdx @@ -142,11 +142,11 @@ eden_ai = ProviderProfile( env_vars=("EDENAI_API_KEY",), base_url="https://api.edenai.run/v3", auth_type="api_key", - default_aux_model="mistral/mistral-small-latest", + default_aux_model="mistral/mistral-small-2603", fallback_models=( - "anthropic/claude-sonnet-4-5", - "openai/gpt-4o", - "mistral/mistral-small-latest", + "anthropic/claude-sonnet-5", + "openai/gpt-5.5", + "mistral/mistral-small-2603", ), ) diff --git a/v3/integrations/pydantic-ai.mdx b/v3/integrations/pydantic-ai.mdx index 748214a..7c55515 100644 --- a/v3/integrations/pydantic-ai.mdx +++ b/v3/integrations/pydantic-ai.mdx @@ -49,7 +49,7 @@ from pydantic_ai.models.openai import OpenAIChatModel from pydantic_ai.providers.openai import OpenAIProvider model = OpenAIChatModel( - "openai/gpt-4o", + "openai/gpt-5.5", provider=OpenAIProvider( api_key="YOUR_EDEN_AI_API_KEY", # Get from https://app.edenai.run base_url="https://api.edenai.run/v3", @@ -67,22 +67,21 @@ print(result.output) Access models from multiple providers using the `provider/model` format: **OpenAI** -- `openai/gpt-4o` -- `openai/gpt-4o-mini` -- `openai/gpt-4-turbo` +- `openai/gpt-5.5` +- `openai/gpt-5-mini` **Anthropic** -- `anthropic/claude-sonnet-4-5` -- `anthropic/claude-opus-4-5` +- `anthropic/claude-sonnet-5` +- `anthropic/claude-opus-4-8` - `anthropic/claude-haiku-4-5` **Google** - `google/gemini-2.5-pro` -- `google/gemini-2.5-flash` +- `google/gemini-3.5-flash` **Mistral** -- `mistral/mistral-large-latest` -- `mistral/mistral-small-latest` +- `mistral/mistral-large-2512` +- `mistral/mistral-small-2603` ## Structured Output @@ -102,7 +101,7 @@ class City(BaseModel): population: int model = OpenAIChatModel( - "anthropic/claude-sonnet-4-5", + "anthropic/claude-sonnet-5", provider=OpenAIProvider( api_key="YOUR_EDEN_AI_API_KEY", base_url="https://api.edenai.run/v3", @@ -127,7 +126,7 @@ from pydantic_ai.models.openai import OpenAIChatModel from pydantic_ai.providers.openai import OpenAIProvider model = OpenAIChatModel( - "anthropic/claude-sonnet-4-5", + "anthropic/claude-sonnet-5", provider=OpenAIProvider( api_key="YOUR_EDEN_AI_API_KEY", base_url="https://api.edenai.run/v3", @@ -158,7 +157,7 @@ from pydantic_ai.providers.openai import OpenAIProvider from pydantic_ai.exceptions import ModelHTTPError, UnexpectedModelBehavior model = OpenAIChatModel( - "openai/gpt-4o", + "openai/gpt-5.5", provider=OpenAIProvider( api_key="YOUR_EDEN_AI_API_KEY", base_url="https://api.edenai.run/v3", @@ -190,7 +189,7 @@ from pydantic_ai.models.openai import OpenAIChatModel from pydantic_ai.providers.openai import OpenAIProvider model = OpenAIChatModel( - "openai/gpt-4o", + "openai/gpt-5.5", provider=OpenAIProvider( api_key=os.getenv("EDEN_AI_API_KEY"), base_url="https://api.edenai.run/v3",