Merge to production 20260721

.gitignore

@@ -148,3 +148,8 @@ dmypy.json
 .env.test
 
 aixplain-dev/
+
+# brusk:worktree-ignores
+.brusk/
+.claude/
+CLAUDE.md

.pre-commit-config.yaml

@@ -27,3 +27,24 @@ repos:
         pass_filenames: false
         types: [python]
         always_run: true
+        additional_dependencies:
+          - coverage
+          - pytest
+          - pytest-mock
+          - pytest-rerunfailures
+          - pytest-xdist
+          - requests-mock
+          - Babel>=2.12.0
+          - requests>=2.1.0
+          - tqdm>=4.1.0
+          - pandas>=2.0.0
+          - python-dotenv>=1.0.0
+          - validators>=0.20.0
+          - filetype>=1.2.0
+          - click>=7.1.2
+          - PyYAML>=6.0.1
+          - dataclasses-json>=0.5.2
+          - Jinja2==3.1.6
+          - sentry-sdk>=1.0.0
+          - pydantic>=2.10.6
+          - filelock>=3.0.0

README.md

@@ -1,8 +1,8 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/aixplain-logo-light.png">
-    <source media="(prefers-color-scheme: light)" srcset="docs/assets/aixplain-logo-dark.png">
-    <img src="docs/assets/aixplain-logo-dark.png" alt="aixplain" width="520">
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/aixplain-logo-light.svg">
+    <source media="(prefers-color-scheme: light)" srcset="docs/assets/aixplain-logo-dark.svg">
+    <img src="docs/assets/aixplain-logo-dark.svg" alt="aixplain" width="420">
   </picture>
 </p>
 
@@ -11,53 +11,47 @@
 <p align="center">
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-2ea44f?style=flat-square" alt="License"></a>
   <a href="https://studio.aixplain.com/browse"><img src="https://img.shields.io/badge/Marketplace-900%2B%20models%20%26%20tools-0b74de?style=flat-square" alt="Marketplace size"></a>
-  <a href="https://console.aixplain.com/settings/keys"><img src="https://img.shields.io/badge/%F0%9F%94%91%20PAYG%20API%20key-Settings-0b74de?style=flat-square" alt="PAYG API key"></a>
   <a href="https://discord.gg/aixplain"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord"></a>
 </p>
 
-**Build, deploy, and govern autonomous AI agents — in a few lines of Python.**
+**Build, deploy, and run autonomous AI agents — governed by default, in a few lines of Python.**
 
-_The fastest way to deploy managed, multi-agent systems with runtime governance — on any infrastructure._
+aixplain is the operating system for autonomous AI: multi-agent orchestration with **runtime governance on every action**, across cloud, on-prem, edge, and local. The full lifecycle — build → evaluate → deploy → monitor → evolve — on one runtime, instead of stitching tools together.
 
-aixplain is the operating system for autonomous AI — **multi-agent orchestration and runtime governance across cloud, on-prem, edge, and fully air-gapped environments**. It spans the full lifecycle — **development → evaluation → deployment → monitoring → evolution** — so you ship faster instead of stitching tools together. Agents plan, call models and tools, run code, and adapt at runtime, with **agents-in-the-loop** governance enforced on every execution.
+**On your terms** — **your data** in your perimeter, **your cost** free on local models and tools, pay as you go in the cloud, **your independence** across any model or infrastructure, no lock-in.
 
-**Build any kind of agent on one runtime** — knowledge (RAG), data, custom-logic, integration, and team agents — with built-in memory, multimodality, and file handling.
-
-Develop your way — **SDK, API, CLI, and MCP** environments all run on the same runtime layer, backed by an integrated marketplace of **900+ AI models, tools, and integrations from 70+ vendors** (OpenAI, Anthropic, Gemini, Firecrawl, Tavily, SerpAPI, a code-execution sandbox, and more). **One API key, one bill**, pay as you go — no per-vendor keys or contracts.
+Build any agent — knowledge (RAG), data, custom-logic, integration, and team — via **SDK, API, CLI, or MCP**, on a marketplace of **900+ models, tools, and integrations**.
 
 ## Why aixplain
 
 Less to build, less to operate:
 
 - **Deploy with one call** — `agent.save()` promotes an agent to a persistent, versioned endpoint; no Dockerfiles, queues, or autoscaling to manage.
-- **No integration glue** — reach [900+ models, tools, and integrations](#mcp-server-marketplace) through one key; skip per-provider SDKs, auth, and rate-limit handling.
-- **Governance you don't have to code** — allow-lists, per-asset permissions, rate and usage limits, and enterprise RBAC enforced at runtime.
+- **No integration glue** — reach [900+ models, tools, and integrations](#marketplace) through one key; skip per-provider SDKs, auth, and rate-limit handling.
+- **Guardrails you don't have to build** — allow-lists, per-asset permissions, rate and usage limits, and access control enforced at runtime.
 - **Self-debugging** — step-level traces of every plan, tool call, and outcome.
-- **Run it anywhere** — the same definition runs serverless, on-prem, at the edge, or fully air-gapped.
+- **Run it anywhere** — the same definition runs in the cloud, on-prem, at the edge, or locally.
+- **Works with your coding agent** — native [MCP support](#marketplace) for MCP-compatible IDEs and coding agents.
 
-| | aixplain SDK | Other agent frameworks |
-|---|---|---|
-| Governance | Asset/action allow-lists, per-asset permissions, rate and usage limits, and enterprise RBAC | Usually custom code or external guardrails |
-| Models and tools | 900+ models and tools with one API key | Provider-by-provider setup |
-| Deployment | Cloud (instant) or on-prem | Usually self-assembled runtime and infra |
-| Observability | Built-in traces and dashboards | Varies by framework |
-| [Coding-agent workflows](https://github.com/aixplain/aiXplain/tree/main/skills/aixplain-agent-builder) | Works natively with MCP-compatible coding agents and IDEs | Usually not a first-class workflow target |
+## How it works
 
-## Agentic OS
+The portable runtime behind aixplain agents: orchestration, governed asset serving, and observability across cloud, on-prem, edge, and local. See the [documentation](https://docs.aixplain.com) for the full architecture.
 
-Agentic OS is the portable runtime platform behind aixplain agents — orchestration, governed asset serving, and observability across Cloud (instant), on-prem, edge, and air-gapped deployments. See the [documentation](https://docs.aixplain.com) for the full architecture.
+<p align="center">
+  <img src="docs/assets/aixplain-agentic-os-architecture.svg" alt="aixplain Agentic OS architecture — governed execution loop (Planner, Orchestrator, Inspector, Bodyguard) over the infrastructure services, deployable on cloud, on-prem, edge, and local" width="100%">
+</p>
 
 ---
 
 ## Quick start
 
-> **This README documents SDK v2, the default API.** SDK v1 (the legacy factory API) keeps working until **end of July 2026**, after which v2 is the only supported surface.
+> **This README documents SDK v2, the default API.** SDK v1 (the legacy factory API) keeps working until **August 1, 2026**, after which v2 is the only supported surface.
 
 ```bash
 pip install aixplain
 ```
 
-Get your API key from your [aixplain account](https://console.aixplain.com/settings/keys), then expose it to the SDK:
+Get your API key from your aixplain account, then expose it to the SDK:
 
 ```bash
 export AIXPLAIN_API_KEY=<your-key>
@@ -66,7 +60,6 @@ export AIXPLAIN_API_KEY=<your-key>
 ### Create and run your first agent
 
 ```python
-from uuid import uuid4
 from aixplain import Aixplain
 
 aix = Aixplain()  # reads AIXPLAIN_API_KEY from the environment
@@ -75,7 +68,7 @@ search_tool = aix.Tool.get("tavily/tavily-web-search/tavily")
 search_tool.allowed_actions = ["search"]
 
 agent = aix.Agent(
-    name=f"Research agent {uuid4().hex[:8]}",
+    name="Research agent",
     description="Answers questions with concise web-grounded findings.",
     instructions="Use the search tool when needed and cite key findings.",
     tools=[search_tool],
@@ -93,9 +86,8 @@ print(result.data.output)
 ### Build a multi-agent team
 
 ```python
-from uuid import uuid4
 from aixplain import Aixplain
-from aixplain.v2 import EditorConfig, EvaluatorConfig, EvaluatorType, Inspector, InspectorAction, InspectorActionConfig, InspectorSeverity, InspectorTarget
+from aixplain.v2 import Inspector
 
 aix = Aixplain()  # reads AIXPLAIN_API_KEY from the environment
 search_tool = aix.Tool.get("tavily/tavily-web-search/tavily")
@@ -107,29 +99,25 @@ def never_edit(text: str) -> bool:
 def passthrough(text: str) -> str:
     return text
 
+# Config is plain data — strings for action/targets/severity, and a Metric,
+# asset-id string, or callable for the `metric` (the universal judge).
 noop_inspector = Inspector(
-    name=f"noop-output-inspector-{uuid4().hex[:8]}",
-    severity=InspectorSeverity.LOW,
-    targets=[InspectorTarget.OUTPUT],
-    action=InspectorActionConfig(type=InspectorAction.EDIT),
-    evaluator=EvaluatorConfig(
-        type=EvaluatorType.FUNCTION,
-        function=never_edit,
-    ),
-    editor=EditorConfig(
-        type=EvaluatorType.FUNCTION,
-        function=passthrough,
-    ),
+    name="noop-output-inspector",
+    severity="low",
+    targets=["output"],
+    action="edit",
+    metric=never_edit,
+    editor=passthrough,
 )
 
 researcher = aix.Agent(
-    name=f"Researcher {uuid4().hex[:8]}",
+    name="Researcher",
     instructions="Find and summarize reliable sources.",
     tools=[search_tool],
 )
 
 team_agent = aix.Agent(
-    name=f"Research team {uuid4().hex[:8]}",
+    name="Research team",
     instructions="Research the topic and return exactly 5 concise bullet points.",
     subagents=[researcher],
     inspectors=[noop_inspector],
@@ -142,10 +130,6 @@ response = team_agent.run(
 print(response.data.output)
 ```
 
-<div align="center">
-  <img src="docs/assets/aixplain-workflow-teamagent.png" alt="aixplain team-agent runtime flow" title="aixplain" width="70%"/>
-</div>
-
 Execution order:
 
 ```text
@@ -156,20 +140,19 @@ Team agent
 ├── Orchestrator: routes work to the right subagent
 ├── Researcher subagent
 │   └── Tavily search tool: finds and summarizes reliable sources
-├── Inspector: checks the final output through a simple runtime policy
-├── Orchestrator: decides whether another pass is needed
-└── Responder: returns one final answer
+├── Inspector: validates the output against a runtime policy
+└── Orchestrator: composes and returns the final answer
 ```
 
-> **SDK 1 (legacy):** available until end of July 2026 — see the [SDK 1 docs](https://docs.aixplain.com/1.0/).
+> **SDK v1 (legacy):** available until August 1, 2026 — see the [SDK v1 docs](https://docs.aixplain.com/1.0/).
 
 ---
 
-## MCP Server Marketplace
+## Marketplace
 
-[aixplain Marketplace](https://studio.aixplain.com/browse) now also exposes MCP servers for **900+ models and tools**, allowing external clients to access selected **tool, integration, and model assets**, for example **Opus 4.6, Kimi, Qwen, Airtable, and Slack**, through **aixplain-hosted MCP endpoints** with a single API key 🔑.
+The [aixplain Marketplace](https://studio.aixplain.com/browse) is a catalog of **900+ models, tools, and integrations**. Every asset is reachable through the same three outlets — **SDK, API, and MCP** — with a single API key 🔑.
 
-Read the full MCP setup guide in the [MCP servers docs](https://docs.aixplain.com/api-reference/mcp-servers).
+For MCP-compatible clients and IDEs, assets (for example Opus 4.6, Kimi, Qwen, Airtable, Slack) are served through aixplain-hosted MCP endpoints. See the [MCP servers docs](https://docs.aixplain.com/api-reference/mcp-servers).
 
 ```json
 {
@@ -185,32 +168,11 @@ Read the full MCP setup guide in the [MCP servers docs](https://docs.aixplain.co
 
 ---
 
-## Core concepts
-
-| Concept | What it is |
-|---|---|
-| **Agent** | An autonomous entity that reasons, plans, and uses tools to complete a task. |
-| **Team agent** | Multiple specialized agents coordinated by a planner and orchestrator at runtime. |
-| **Tool** | A capability an agent can invoke — a model, an integration, or code (Python/SQL). |
-| **Model** | An LLM, utility, or index asset from the [marketplace](https://studio.aixplain.com/browse). |
-| **Integration** | A connector to an external service (Slack, Airtable, Gmail, and more) that an agent can act through. |
-| **Micro-agents** | Built-in governance components that run inline on every execution: Mentalist (planning), Orchestrator (routing), Inspector (validation — e.g. block pip installs or network access), Bodyguard (security), Responder (formatting). |
-| **Meta-agent** | An agent that improves other agents — the Evolver monitors KPIs and refines behavior over time. |
-
-See the [documentation](https://docs.aixplain.com) for the full API reference.
-
----
-
 ## Data handling and deployment
 
-aixplain applies runtime governance and enterprise controls by default:
-
-- **We do not train on your data** — your data is not used to train foundation models.
-- **No data retained by default** — agent memory is opt-in (short-term and long-term).
-- **SOC 2 Type II certified** — enterprise security and compliance posture.
-- **Runtime policy enforcement** — Inspector and Bodyguard govern every agent execution, with allow-lists for assets and actions, per-asset permissions, rate and usage limits, and enterprise RBAC.
-- **Portable deployment options** — Cloud (instant) or on-prem (including VPC and air-gapped environments).
-- **Encryption** — TLS 1.2+ in transit and encrypted storage at rest.
+- **Your data stays yours** — never used to train foundation models; agent memory is opt-in. SOC 2 Type II; TLS 1.2+ in transit, encrypted at rest.
+- **Governed at runtime** — Inspector and Bodyguard enforce allow-lists, per-asset permissions, rate and usage limits, and access control on every execution.
+- **Deploy anywhere** — cloud, on-prem, edge, or local; air-gapped and VPC available on-prem or local.
 
 Learn more at aixplain [Security](https://aixplain.com/security/) and aixplain [pricing](https://aixplain.com/pricing/).
 

aixplain/utils/user_info_utils.py

@@ -33,7 +33,12 @@
 
 @lru_cache(maxsize=1)
 def _fetch_ipinfo() -> Dict[str, Any]:
-    """Fetch and cache the ipinfo.io payload for the current public IP."""
+    """Fetch and cache the ipinfo.io payload for the current public IP.
+
+    All errors degrade silently to ``{}`` — this is auxiliary metadata
+    and an outage / network-isolation / test-mock should never break a
+    caller's run.
+    """
     try:
         response = requests.get(_IPINFO_URL, timeout=_IPINFO_TIMEOUT)
         response.raise_for_status()

aixplain/v1/modules/pipeline/asset.py

@@ -260,12 +260,16 @@ def run(
             if response_version == "v1":
                 polling_response["elapsed_time"] = end - start
                 return polling_response
+            # `status`/`completed` were already read above via subscript access, which
+            # works for both a PipelineResponse and the plain dict __polling may return
+            # when polling fails. Use subscript/`in` access here too so a failed run
+            # doesn't raise AttributeError on a dict.
             return PipelineResponse(
                 status=status,
                 completed=completed,
-                error=polling_response.get("error"),
+                error=polling_response["error"] if "error" in polling_response else None,
                 elapsed_time=end - start,
-                data=polling_response.get("data", {}),
+                data=polling_response["data"] if "data" in polling_response else {},
                 **kwargs,
             )
 

aixplain/v2/__init__.py

@@ -3,22 +3,20 @@
 from .core import Aixplain
 from .rlm import RLM, RLMResult
 from .utility import Utility
-from .agent import Agent, ContextOverflowStrategy
+from .agent import Agent, Budget, ContextOverflowStrategy
 from .tool import Tool
+from .skill import Skill
 from .actions import Input, Inputs, Action, Actions
+from .integration import TriggerTypeSpec, TriggerEventOption, TriggerTypes
+from .trigger import Trigger, TriggerConfiguration, TriggerRepeatRule
 from .file import Resource
 from .upload_utils import FileUploader, upload_file, validate_file_for_upload
-from .inspector import (
-    Inspector,
-    InspectorTarget,
-    InspectorAction,
-    InspectorOnExhaust,
-    InspectorSeverity,
-    InspectorActionConfig,
-    EvaluatorType,
-    EvaluatorConfig,
-    EditorConfig,
-    PrebuiltInspector,
+from .inspector import Inspector
+from .session import (
+    ExecutionConfig,
+    Session,
+    SessionMessage,
+    SessionMessageAttachment,
 )
 from .meta_agents import Debugger, DebugResult
 from .agent_progress import AgentProgressTracker, ProgressFormat
@@ -84,6 +82,11 @@
     EvolveType,
     CodeInterpreterModel,
     SplittingOptions,
+    SessionStatus,
+    RunStatus,
+    MessageRole,
+    Reaction,
+    AttachmentType,
 )
 
 __all__ = [
@@ -92,24 +95,21 @@
     "RLMResult",
     "Utility",
     "Agent",
+    "Budget",
     "ContextOverflowStrategy",
     "Tool",
+    "Skill",
     "Resource",
     "FileUploader",
     "upload_file",
     "validate_file_for_upload",
-    # Inspector classes
+    # Session classes
+    "Session",
+    "SessionMessage",
+    "SessionMessageAttachment",
+    "ExecutionConfig",
+    # Inspector
     "Inspector",
-    "InspectorTarget",
-    "InspectorAction",
-    "InspectorOnExhaust",
-    "InspectorSeverity",
-    "InspectorActionConfig",
-    "EvaluatorType",
-    "EvaluatorConfig",
-    "EditorConfig",
-    "PrebuiltInspector",
-    "ModelResponse",
     # Meta-agents
     "Debugger",
     "DebugResult",
@@ -180,9 +180,21 @@
     "EvolveType",
     "CodeInterpreterModel",
     "SplittingOptions",
+    "SessionStatus",
+    "RunStatus",
+    "MessageRole",
+    "Reaction",
+    "AttachmentType",
     # Actions / Inputs hierarchy
     "Input",
     "Inputs",
     "Action",
     "Actions",
+    # Triggers
+    "Trigger",
+    "TriggerConfiguration",
+    "TriggerRepeatRule",
+    "TriggerTypeSpec",
+    "TriggerEventOption",
+    "TriggerTypes",
 ]