diff --git a/concepts/platform/depot.mdx b/concepts/platform/depot.mdx new file mode 100644 index 0000000..1c0f23e --- /dev/null +++ b/concepts/platform/depot.mdx @@ -0,0 +1,20 @@ +--- +title: "Depot" +description: "Catalog of hardened models and pre-validated building blocks for agent safety." +--- + + +Depot is in development and not yet generally available. This page previews what it will do. + + +Depot is Vijil's catalog of hardened models and building blocks for agent safety. Instead of assembling and validating protections from scratch, you draw on components that Vijil has already tested and tuned, reducing months of security work to days. + +## What Depot Provides + +- **Guardrail models** tuned for agent safety, ready to drop into [Dome](/concepts/platform/dome). +- **Hardened LLMs** optimized for specific tasks. +- **Pre-validated components** that shorten the path from prototype to a production-ready, trustworthy Agent. + +## How Depot Fits In + +Depot supplies the raw material the rest of the platform builds on. [Dome](/concepts/platform/dome) can enforce protection using Guardrail models from Depot, and [Diamond](/concepts/platform/diamond) evaluations give you the evidence to choose the right hardened components for your use case. diff --git a/developer-guide/agentic/quickstart.mdx b/developer-guide/agentic/quickstart.mdx index 7db0948..1c8594e 100644 --- a/developer-guide/agentic/quickstart.mdx +++ b/developer-guide/agentic/quickstart.mdx @@ -3,19 +3,21 @@ title: "Quickstart" description: "Install Vijil, register an Agent, run a trust Evaluation, and retrieve results, through the CLI, MCP, or REST API." --- -Vijil exposes three programmatic interfaces. This quickstart takes you from a fresh setup to a completed trust Evaluation. The workflow is the same for all three, so pick the tab for the interface you prefer at each step. +Vijil exposes four programmatic interfaces. This quickstart takes you from a fresh setup to a completed trust Evaluation. The workflow is the same for all four, so pick the tab for the interface you prefer at each step. | Interface | Best For | Requires | |-----------|----------|----------| | **CLI** | Scripting, CI/CD gates, headless automation | `vijil-console` | | **MCP** | Interactive development, natural language | Claude Code + `vijil-mcp` | | **REST API** | Custom integrations, non-Python environments | HTTP client + API key | +| **SDK** | Python apps, notebooks, programmatic pipelines | `vijil-sdk` (Python 3.12+) | ## Prerequisites - A [Vijil Console](/developer-guide/deploy-vijil/deploy-vijil-console) deployment and its API gateway URL - An API key for the AI model you want to evaluate -- [Python 3.8](https://www.python.org/) or later (CLI and MCP only) +- A Vijil API key from the Console (**Settings** > **API Keys**) — a client ID and secret — for the SDK +- [Python 3.8](https://www.python.org/) or later (CLI and MCP only; the SDK requires Python 3.12 or later) - [Claude Code](https://claude.ai/code) installed (MCP only) ## Steps @@ -69,6 +71,25 @@ Vijil exposes three programmatic interfaces. This quickstart takes you from a fr export VIJIL_URL="https://console-api.example.com" ``` + + Install `vijil-sdk`, which provides the `vijil` Python SDK: + + + ```bash pip + pip install vijil-sdk + ``` + + ```bash poetry + poetry add vijil-sdk + ``` + + + The SDK requires Python 3.12 or later. Verify the import: + + ```bash + python -c "from vijil import Vijil; print('ok')" + ``` + @@ -153,6 +174,28 @@ Vijil exposes three programmatic interfaces. This quickstart takes you from a fr export TEAM_ID="c58aea71-..." ``` + + Create an API key in the Console under **Settings** > **API Keys** — a client ID (`vk_…`) plus a one-time secret shown only at creation. Export the pair; the SDK exchanges it for a short-lived access token automatically: + + ```bash + export VIJIL_CLIENT_ID="vk_..." + export VIJIL_CLIENT_SECRET="..." # shown once at creation + ``` + + Construct the client, pointing it at your Console gateway: + + ```python + from vijil import Vijil + + client = Vijil(gateway="https://console-api.example.com") + ``` + + `Vijil()` reads the credentials from the environment automatically. If you already have a bearer access token, use it directly instead with `VIJIL_API_KEY` or `Vijil(api_key="")` — but note that a bearer token is a JWT that expires 24 hours after it is issued. The client ID and secret do not expire, and the SDK refreshes the token from them automatically, so prefer the pair for long-lived automation. + + + In CI/CD, set `VIJIL_CLIENT_ID` and `VIJIL_CLIENT_SECRET` as secrets rather than committing them. + + @@ -212,6 +255,24 @@ Vijil exposes three programmatic interfaces. This quickstart takes you from a fr export AGENT_ID="a1b2c3d4-..." ``` + + Create an [Agent](/owner-guide/register-agents/what-is-an-agent) configuration for the model you want to evaluate: + + ```python + agent = client.agents.create( + name="My Chat Agent", + url="https://api.openai.com/v1/chat/completions", + ) + print(agent.id) + ``` + + Keep the returned `agent` object, you will pass `agent.id` to the Evaluation. To see all registered Agents at any time: + + ```python + for a in client.agents.list().items: + print(a.id, a.name) + ``` + @@ -241,6 +302,16 @@ Vijil exposes three programmatic interfaces. This quickstart takes you from a fr -H "Authorization: Bearer $TOKEN" ``` + + List the available Harnesses: + + ```python + for harness in client.harnesses.list().items: + print(harness.name) + ``` + + For this quickstart you will use the standard trust Harnesses, which `client.evaluate(..., baseline=True)` runs in the next step. To run a specific custom Harness instead, pass its `harness_id`. + @@ -302,6 +373,16 @@ Vijil exposes three programmatic interfaces. This quickstart takes you from a fr The `status` field progresses through `starting` → `pending` → `running` → `completed` → `saving` → `saved`. + + Start a trust Evaluation against the standard Harnesses. `evaluate` polls until the Evaluation completes, then returns the result: + + ```python + evaluation = client.evaluate(agent.id, baseline=True) + print(evaluation.status) # "completed" + ``` + + Polling runs every 5 seconds by default. Adjust it with the `_poll_interval` argument. `baseline=True` covers the reliability, security, and safety dimensions in a single run. + @@ -339,6 +420,23 @@ Vijil exposes three programmatic interfaces. This quickstart takes you from a fr This returns the detailed results JSON including per-Harness breakdowns, individual Probe results, and analysis. + + Read the [Trust Score](/concepts/trust-score/introduction) and per-dimension breakdown straight off the returned Evaluation: + + ```python + print(evaluation.trust_score) # 0.82 + print(evaluation.dimensions.reliability) + print(evaluation.dimensions.security) + print(evaluation.dimensions.safety) + ``` + + To fetch the latest score for an Agent later, without holding the Evaluation object: + + ```python + score = client.scores.show(agent.id) + print(score.trust_score) + ``` + @@ -375,6 +473,17 @@ Vijil exposes three programmatic interfaces. This quickstart takes you from a fr -o report.pdf ``` + + Download the [Trust Report](/developer-guide/evaluate/understanding-results) for the completed Evaluation as a PDF: + + ```python + pdf_bytes = client.reports.download(evaluation.id) + with open("report.pdf", "wb") as f: + f.write(pdf_bytes) + ``` + + The report summarizes what was tested, how the Agent scored, and where it failed. + @@ -388,6 +497,9 @@ Vijil exposes three programmatic interfaces. This quickstart takes you from a fr Complete list of MCP tools with parameters and example prompts + + Python client, lifecycle methods, resources, models, and errors + Interpret Trust Scores and prioritize what to fix @@ -407,3 +519,5 @@ Vijil exposes three programmatic interfaces. This quickstart takes you from a fr | Tools do not appear in Claude Code | Verify `.mcp.json` is in the project root, then restart Claude Code | | Claude uses Bash instead of MCP tools | Confirm `vijil-mcp` is in your `PATH`: run `which vijil-mcp` | | `401 Unauthorized` from the REST API | Your token expired, request a new one from `POST /auth/jwt/login` | +| `VijilAuthError` from the SDK | Set `VIJIL_CLIENT_ID` and `VIJIL_CLIENT_SECRET` (or `VIJIL_API_KEY`) before constructing `Vijil()` | +| SDK import fails | Ensure you are on Python 3.12 or later, then reinstall with `pip install vijil-sdk` | diff --git a/developer-guide/evaluate/custom-harnesses.mdx b/developer-guide/evaluate/custom-harnesses.mdx index d31696b..66d0ad7 100644 --- a/developer-guide/evaluate/custom-harnesses.mdx +++ b/developer-guide/evaluate/custom-harnesses.mdx @@ -22,15 +22,108 @@ To view the prompts, [Personas](/owner-guide/simulate-environment/personas) and ## Create a Custom Harness Programmatically +### Create Personas and Policies + +[Personas](/owner-guide/simulate-environment/personas) define *who* interacts with your Agent, and [Policies](/owner-guide/simulate-environment/policies) define the *rules* it must follow. Both are optional inputs to custom Harness creation: pass their IDs (`persona_ids` and `policy_ids`) in the next step, and Vijil generates [Probes](/concepts/evaluation-components/probe) that combine each Persona's behavior with each Policy's constraints. Create them first, then reference their IDs when you create the Harness. + + + + + ```bash + # Create a Persona (or copy a built-in one: vijil persona from-preset ) + vijil persona create \ + --name "Frustrated Customer" \ + --role "End user" \ + --intent adversarial + + # Create a Policy from text, then activate it for use in Harnesses + vijil policy create \ + --name "Data Handling Policy" \ + --category privacy \ + --source-text "The agent must not store or repeat personal data." + + vijil policy activate + ``` + + Each command prints the new `id`. Save the Persona and Policy IDs for the next step. List built-in options with `vijil persona preset-list` and `vijil policy preset-list`. + + + + + With the [Vijil MCP server](/developer-guide/agentic/quickstart) configured, ask Claude Code in natural language: + + + Create an adversarial 'Frustrated Customer' persona and a privacy policy that forbids storing personal data + + + Claude creates the Persona and Policy and returns their IDs. + + + + + ```bash + curl -s -X POST "$VIJIL_URL/v1/personas/?team_id=$TEAM_ID" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Frustrated Customer", + "role": "End user", + "intent": "adversarial" + }' + + curl -s -X POST "$VIJIL_URL/v1/policies/?team_id=$TEAM_ID" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Data Handling Policy", + "category": "privacy", + "source_text": "The agent must not store or repeat personal data." + }' + ``` + + Each request returns `201 Created` with an `id`. Save both for the next step. + + + + + ```python + persona = client.personas.create( + name="Frustrated Customer", + role="End user", + intent="adversarial", + ) + + policy = client.policies.create( + name="Data Handling Policy", + category="privacy", + source_text="The agent must not store or repeat personal data.", + ) + + print(persona.id, policy.id) + ``` + + `intent` is one of `benign`, `curious`, `adversarial`, or `malicious`. `category` is one of `privacy`, `ethics`, `security`, `compliance`, `operational`, `brand`, or `custom`. + + + + + +Personas and Policies are reusable across Harnesses. For balanced coverage, combine a benign and an adversarial Persona with the Policies that matter most to your Agent. See [Define Personas](/owner-guide/simulate-environment/personas) and [Define Policies](/owner-guide/simulate-environment/policies) for design guidance. + + ### Create a Harness +Pass the Persona and Policy IDs from the previous step as `persona_ids` and `policy_ids`. Both are optional — omit them to generate a Harness from the Agent description alone. + ```bash vijil harness custom-create \ --name "Customer Support Harness" \ - --agent-id "$AGENT_ID" + --agent-id "$AGENT_ID" \ + --persona-ids '[""]' \ + --policy-ids '[""]' ``` | Flag | Description | Required | @@ -96,6 +189,28 @@ To view the prompts, [Personas](/owner-guide/simulate-environment/personas) and | `description` | Human-readable description | No | | `system_prompt` | System prompt used during Harness generation; defaults to the Agent description if omitted | No | + + + + ```python + harness = client.harnesses.create( + name="Customer Support Harness", + agent_id="", + persona_ids=[""], # optional + policy_ids=[""], # optional + system_prompt="You are a helpful customer support assistant.", # optional + ) + print(harness.id) + ``` + + | Parameter | Description | Required | + |-----------|-------------|----------| + | `name` | Harness display name | Yes | + | `agent_id` | UUID of the Agent under test | Yes | + | `persona_ids` | List of Persona UUID values | No | + | `policy_ids` | List of Policy UUID values | No | + | `system_prompt` | System prompt used during generation; defaults to the Agent description | No | + @@ -114,6 +229,11 @@ vijil harness custom-get curl -s "$VIJIL_URL/v1/custom-harnesses/$HARNESS_ID?team_id=$TEAM_ID" \ -H "Authorization: Bearer $TOKEN" ``` + +```python title="SDK" +harness = client.harnesses.show("") +print(harness.status) +``` | `status` value | Meaning | @@ -137,9 +257,17 @@ vijil harness custom-prompts --json curl -s "$VIJIL_URL/v1/custom-harnesses/$HARNESS_ID/prompts?team_id=$TEAM_ID" \ -H "Authorization: Bearer $TOKEN" ``` + +```python title="SDK" +# No dedicated resource method yet — reach the endpoint through the client's HTTP transport +prompts = client._http.get( + f"/v1/custom-harnesses/{harness_id}/prompts", + params={"team_id": team_id}, +) +``` -Returns an empty list if the Harness is still in `draft` status. +Returns an empty list if the Harness is still in `draft` status. The SDK has no dedicated `prompts` method yet, so the example above calls the endpoint through `client._http`, the same transport the high-level methods use. ### List Custom Harnesses @@ -153,9 +281,14 @@ vijil harness custom-list --agent-id "$AGENT_ID" --status active curl -s "$VIJIL_URL/v1/custom-harnesses/?team_id=$TEAM_ID&status=active" \ -H "Authorization: Bearer $TOKEN" ``` + +```python title="SDK" +for harness in client.harnesses.list().items: + print(harness.id, harness.name, harness.status) +``` -Both support filtering by `agent_id` and `status`, with `limit` and `offset` for pagination. +Both support filtering by `agent_id` and `status`, with `limit` and `offset` for pagination. The SDK's `client.harnesses.list()` returns standard and custom Harnesses together. ### Cancel Generation @@ -170,8 +303,18 @@ vijil harness custom-cancel curl -s -X POST "$VIJIL_URL/v1/custom-harnesses/$HARNESS_ID/cancel?team_id=$TEAM_ID" \ -H "Authorization: Bearer $TOKEN" ``` + +```python title="SDK" +# No dedicated resource method yet — reach the endpoint through the client's HTTP transport +client._http.post( + f"/v1/custom-harnesses/{harness_id}/cancel", + params={"team_id": team_id}, +) +``` +The SDK has no dedicated `cancel` method yet, so the example above calls the endpoint through `client._http`, the same transport the high-level methods use. + ### Delete a Harness @@ -184,6 +327,10 @@ vijil harness custom-delete --yes curl -s -X DELETE "$VIJIL_URL/v1/custom-harnesses/$HARNESS_ID?team_id=$TEAM_ID" \ -H "Authorization: Bearer $TOKEN" ``` + +```python title="SDK" +client.harnesses.delete("") +``` ## Next Steps diff --git a/developer-guide/evaluate/running-evaluations.mdx b/developer-guide/evaluate/running-evaluations.mdx index ebb65c2..6206e08 100644 --- a/developer-guide/evaluate/running-evaluations.mdx +++ b/developer-guide/evaluate/running-evaluations.mdx @@ -1,13 +1,13 @@ --- title: 'Run Evaluations' -description: 'Start, monitor, and retrieve trust Evaluations programmatically using the CLI, REST API, or MCP.' +description: 'Start, monitor, and retrieve trust Evaluations programmatically using the CLI, MCP, REST API, or Python SDK.' --- [Vijil Evaluate](https://vijil.ai/evaluate) is a quality assurance framework that automates the testing of LLM applications. An **Evaluation** in Vijil is an automated test run where you select one or more AI agents and a test [Harness](/concepts/evaluation-components/harness) (covering [Security](/concepts/trust-score/security), [Reliability](/concepts/trust-score/reliability), and [Safety](/concepts/trust-score/safety)) to systematically assess the quality, safety, and reliability of LLM applications. ## Prerequisites -- CLI configured and authenticated, or a Bearer token from `POST /auth/jwt/login`, see the [Quickstart](/developer-guide/agentic/quickstart) +- CLI configured and authenticated, a Bearer token from `POST /auth/jwt/login`, or the SDK authenticated with a Vijil API key, see the [Quickstart](/developer-guide/agentic/quickstart) - A registered [Agent](/tutorials/manage-agents) and its UUID ## Start an Evaluation @@ -45,6 +45,32 @@ description: 'Start, monitor, and retrieve trust Evaluations programmatically us Claude calls `eval_run` with `wait=True` and reports back Trust Scores when the evaluation finishes. + + + + `client.evaluate()` starts the Evaluation and polls until it completes, then returns the result: + + ```python + from vijil import Vijil + + client = Vijil() + evaluation = client.evaluate("", baseline=True) + + print(evaluation.trust_score) # 0.82 + print(evaluation.dimensions.reliability) + print(evaluation.dimensions.security) + print(evaluation.dimensions.safety) + ``` + + | Parameter | Description | Required | + |-----------|-------------|----------| + | `agent_id` | Agent ID or alias | Yes | + | `baseline` | Run the standard trust Harnesses (reliability, security, safety) | | + | `harness_id` | Run a specific custom Harness instead of the baseline | | + | `_poll_interval` | Seconds between status checks (default `5.0`) | | + + Pass either `baseline=True` or a `harness_id`. To start without blocking, call `client.evaluations.create(agent_id="", baseline=True)` and poll `client.evaluations.show()` yourself. + @@ -101,6 +127,11 @@ vijil eval status curl -s "$VIJIL_URL/evaluations/$EVAL_ID" \ -H "Authorization: Bearer $TOKEN" ``` + +```python title="SDK" +evaluation = client.evaluations.show("") +print(evaluation.status) +``` When the status reaches `completed`, the response includes per-Harness Trust Scores: @@ -130,6 +161,11 @@ vijil eval results-detail --json | jq '.scores' curl -s "$VIJIL_URL/evaluation-results/$EVAL_ID/results?team_id=$TEAM_ID" \ -H "Authorization: Bearer $TOKEN" ``` + +```python title="SDK" +score = client.scores.show("") +print(score.trust_score, score.reliability, score.security, score.safety) +``` ## Generate a Report @@ -152,6 +188,12 @@ curl -s "$VIJIL_URL/evaluations/$EVAL_ID/pdf?team_id=$TEAM_ID" \ -H "Authorization: Bearer $TOKEN" \ -o report.pdf ``` + +```python title="SDK" +pdf_bytes = client.reports.download("") +with open("report.pdf", "wb") as f: + f.write(pdf_bytes) +``` ## List and Cancel Evaluations @@ -168,9 +210,15 @@ vijil eval cancel ```bash title="Delete" vijil eval delete ``` + +```python title="SDK" +page = client.evaluations.list(agent_id="") +for evaluation in page.items: + print(evaluation.id, evaluation.status) +``` -Use `GET /evaluations/` and `POST /evaluations/{evaluation_id}/cancel` for the REST API equivalents. +Use `GET /evaluations/` and `POST /evaluations/{evaluation_id}/cancel` for the REST API equivalents. The SDK exposes `client.evaluations.list()` and `client.evaluations.show()`; cancel and delete are available through the CLI and REST API. ## Next Steps diff --git a/developer-guide/getting-started/introduction.mdx b/developer-guide/getting-started/introduction.mdx index 5fd0af8..f108f3e 100644 --- a/developer-guide/getting-started/introduction.mdx +++ b/developer-guide/getting-started/introduction.mdx @@ -4,7 +4,7 @@ description: 'Integrate evaluation and protection into your development workflow --- -**TL;DR:** Vijil integrates into your development workflow via MCP (natural language), CLI (`vijil-console`), or REST API. Diamond evaluates your [agent](/owner-guide/register-agents/what-is-an-agent) before deployment; Dome protects it at runtime. You get a [Trust Score](/concepts/trust-score/introduction) (0–100) with specific failures you can fix and a deployment gate you can automate in CI/CD. +**TL;DR:** Vijil integrates into your development workflow via MCP (natural language), CLI (`vijil-console`), REST API, or the Python SDK (`vijil-sdk`). Diamond evaluates your [agent](/owner-guide/register-agents/what-is-an-agent) before deployment; Dome protects it at runtime. You get a [Trust Score](/concepts/trust-score/introduction) (0–100) with specific failures you can fix and a deployment gate you can automate in CI/CD. ## The Problem with Testing Agents @@ -27,7 +27,7 @@ Vijil provides two products that work together: ## Integration Methods -Vijil exposes three interfaces. Choose the one that fits your workflow, or mix them: +Vijil exposes four interfaces. Choose the one that fits your workflow, or mix them: ### At a Glance @@ -36,8 +36,9 @@ Vijil exposes three interfaces. Choose the one that fits your workflow, or mix t | **MCP** | Interactive development, natural language evaluation | Claude Code + `vijil-mcp` | | **CLI** | CI/CD gates, scripting, headless automation | `vijil-console` package | | **REST API** | Custom integrations, non-Python environments | HTTP client + API key | +| **SDK** | Python apps, notebooks, programmatic pipelines | `vijil-sdk` package (Python 3.12+) | - + **Natural language, no commands.** Connect Claude Code to your Console and evaluate agents through conversation. Best for interactive development and exploration. @@ -47,6 +48,9 @@ Vijil exposes three interfaces. Choose the one that fits your workflow, or mix t **HTTP requests.** Call the Console API directly from any language. Best for custom integrations, dashboards, and non-Python environments. + + **Native Python.** Install `vijil-sdk` and drive evaluations from your own code. Best for Python apps, notebooks, and programmatic pipelines. + ## Three Developer Workflows @@ -92,9 +96,9 @@ Each evaluation produces a **Trust Score** (0–100) with breakdowns by dimensio ## Time to First Trust Score -The fastest path is [MCP](/developer-guide/agentic/quickstart): install `vijil-mcp`, connect Claude Code, and ask it to run an evaluation, with no commands to learn. If you prefer the terminal, the [CLI path in the Quickstart](/developer-guide/agentic/quickstart) takes you from install to a completed evaluation in minutes. For custom integrations or non-Python environments, the [REST API](/developer-guide/agentic/quickstart) accepts standard HTTP requests and returns results as JSON. +The fastest path is [MCP](/developer-guide/agentic/quickstart): install `vijil-mcp`, connect Claude Code, and ask it to run an evaluation, with no commands to learn. If you prefer the terminal, the [CLI path in the Quickstart](/developer-guide/agentic/quickstart) takes you from install to a completed evaluation in minutes. For custom integrations or non-Python environments, the [REST API](/developer-guide/agentic/quickstart) accepts standard HTTP requests and returns results as JSON. To drive evaluations from Python code, the [SDK](/developer-guide/sdk/setup) wraps the same workflow in a typed client. -All three paths require a running [Vijil Console deployment](/developer-guide/deploy-vijil/deploy-vijil-console) and a registered [Agent](/owner-guide/register-agents/what-is-an-agent) endpoint. +All four paths require a running [Vijil Console deployment](/developer-guide/deploy-vijil/deploy-vijil-console) and a registered [Agent](/owner-guide/register-agents/what-is-an-agent) endpoint. ## Integration Points diff --git a/developer-guide/sdk/lifecycle-methods.mdx b/developer-guide/sdk/lifecycle-methods.mdx new file mode 100644 index 0000000..d74e98e --- /dev/null +++ b/developer-guide/sdk/lifecycle-methods.mdx @@ -0,0 +1,137 @@ +--- +title: "Lifecycle Methods" +description: "High-level Vijil client methods that drive the Agent trust lifecycle: evaluate, test, adapt, and protect." +--- + +Lifecycle methods are high-level workflows on the `Vijil` client. Each maps to a stage of the Agent trust lifecycle and, where an operation runs asynchronously, polls until it completes by default. + +| Method | What It Does | Returns | +|--------|--------------|---------| +| `client.evaluate()` | Measure an Agent against known standards | `Evaluation` | +| `client.test()` | Explore for weaknesses under adversarial pressure | `Job` | +| `client.adapt()` | Improve an Agent through corrective evolution | `Job` | +| `client.protect()` | Configure Dome runtime Guardrails | `DomeConfig` | + + +`evaluate` measures against known standards, like a certification exam. `test` explores for unknown weaknesses through adversarial pressure, like a penetration test. Both produce Trust Scores. + + +## `client.evaluate()` + +Run an Evaluation and poll until it completes. + +```python +evaluation = client.evaluate( + "agent-id", + baseline=True, # use the standard trust Harnesses + # harness_id="h-abc", # OR use a specific Harness (mutually exclusive with baseline) +) + +print(evaluation.status) # "completed" +print(evaluation.trust_score) # 0.82 +print(evaluation.dimensions) # Dimensions(reliability=0.9, security=0.8, safety=0.75) +``` + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `agent_id` | `str` | — | Agent ID or alias | +| `baseline` | `bool` | `False` | Run the standard trust Harnesses (reliability, security, safety) | +| `harness_id` | `str \| None` | `None` | Run a specific [Harness](/concepts/evaluation-components/harness) instead of the baseline | +| `_poll_interval` | `float` | `5.0` | Seconds between status checks | + +Returns an [`Evaluation`](/developer-guide/sdk/models-errors). Pass either `baseline=True` or a `harness_id`, not both. + +## `client.test()` + +Create a Red Swarm test engagement and, by default, poll until it finishes. + +```python +job = client.test( + "agent-id", + mode="adaptive", # or "comprehensive" + no_wait=False, # True to return immediately +) + +print(job.status) # "completed" +print(job.id) # "job-abc123" +``` + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `agent_id` | `str` | — | Agent ID or alias | +| `mode` | `str` | `"adaptive"` | `"adaptive"` adjusts strategy from responses; `"comprehensive"` sweeps all categories | +| `no_wait` | `bool` | `False` | Return immediately without polling | +| `tool` | `str` | `"diamond_security"` | Red-team tool to use | +| `purpose` | `str` | `""` | Description of the Agent's purpose | +| `categories` | `list[str] \| None` | `None` | Test categories, for example `["injection"]` | + +Returns a [`Job`](/developer-guide/sdk/models-errors). + +## `client.adapt()` + +Create a corrective evolution job that improves an existing Agent based on weaknesses found by evaluation or testing. + +```python +job = client.adapt("agent-id", mode="config") +print(job.status) # "completed" +``` + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `agent_id` | `str` | — | Agent ID or alias | +| `mode` | `str` | `"config"` | `"prompt"`, `"config"`, `"code"`, or `"dome"` | +| `no_wait` | `bool` | `False` | Return immediately without polling | + +Returns a [`Job`](/developer-guide/sdk/models-errors). After adaptation completes, review and apply the resulting [proposals](/developer-guide/sdk/resources#client-proposals). + +## `client.protect()` + +Configure [Dome](/developer-guide/protect/overview) runtime Guardrails for an Agent. + +```python +dome = client.protect( + "agent-id", + guards=["prompt_injection", "pii"], + mode="enforce", +) + +print(dome.mode) # "enforce" +print(dome.guards) # ["prompt_injection", "pii"] +``` + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `agent_id` | `str` | — | Agent ID or alias | +| `policy_id` | `str \| None` | `None` | Policy to apply | +| `guards` | `list[str] \| None` | `None` | [Guard](/concepts/defense/guard) names | +| `mode` | `str` | `"enforce"` | `"enforce"` blocks threats, `"monitor"` logs only, `"disabled"` turns Guardrails off | + +Returns a [`DomeConfig`](/developer-guide/sdk/models-errors). + +## Preview Methods + + +The following methods target Console routes that are not yet generally available. Their signatures are stable, but calls fail until the corresponding Console capability ships. + + +| Method | What It Does | Returns | +|--------|--------------|---------| +| `client.discover()` | Find Agents in GitHub repositories or cloud infrastructure | `Page[DiscoveredAgent]` | +| `client.register()` | Convert Agent source into an A2A card and genome | `dict` | +| `client.evolve()` | Create a new Agent through generative evolution | `Job` | +| `client.deploy()` | Deploy an Agent to a production runtime | `Deployment` | + +```python +# Discover Agents in a GitHub organization or a Kubernetes namespace +agents = client.discover(github_org="acme-corp") +agents = client.discover(provider="k8s", namespace="production") + +# Register an Agent from a GitHub URL or a local directory +result = client.register("https://github.com/acme/my-agent") + +# Create a new Agent from a spec, a file, or a natural-language description +job = client.evolve(description="A travel booking agent for flights and hotels") + +# Deploy an Agent to a runtime +deployment = client.deploy("agent-id", runtime="agentcore") +``` diff --git a/developer-guide/sdk/models-errors.mdx b/developer-guide/sdk/models-errors.mdx new file mode 100644 index 0000000..59caf35 --- /dev/null +++ b/developer-guide/sdk/models-errors.mdx @@ -0,0 +1,207 @@ +--- +title: "Models and Errors" +description: "Return types the Vijil SDK produces and the exception hierarchy it raises." +--- + +Every SDK call returns a typed model and raises a typed exception on failure. All models inherit from `VijilModel` (a Pydantic `BaseModel` configured with `extra="ignore"`), and all exceptions inherit from `VijilError`. + +## Models + +### `Page[T]` + +Generic paginated response returned by every `list()` method. + +```python +page = client.agents.list() +page.items # list[T] — the results +page.total # int — total count +page.has_more # bool — whether more results exist +``` + +`Page[T]` handles the Console's varying response shapes (`items` or `results` keys, `total` or `count` fields) transparently. + +### `Evaluation` + +```python +evaluation.id # str (UUID) +evaluation.agent_id # str | None +evaluation.status # str — "pending", "running", "completed", "failed" +evaluation.harness_names # list[str] | None +evaluation.trust_score # float | None +evaluation.dimensions # Dimensions | None +``` + +### `Dimensions` + +```python +dimensions.reliability # float | None +dimensions.security # float | None +dimensions.safety # float | None +``` + +### `Job` + +```python +job.id # str (UUID) +job.agent_id # str | None +job.status # str — "pending", "running", "completed", "failed", "cancelled" +job.mode # str | None +job.created_at # str | None +job.error # str | None +``` + +### `Agent` + +```python +agent.id # str (UUID) +agent.name # str +agent.team_id # str | None +agent.url # str | None +agent.framework # str | None +agent.hub # str | None +agent.model_name # str | None +agent.status # str | None +``` + +### `TrustScore` + +```python +score.agent_id # str +score.trust_score # float | None +score.reliability # float | None +score.security # float | None +score.safety # float | None +``` + +### `DomeConfig` + +```python +dome.id # str | None +dome.agent_id # str | None +dome.guards # list[str] | None +dome.mode # str | None +dome.input_guards # list[str] | None +dome.output_guards # list[str] | None +``` + +### `Harness` + +```python +harness.id # str +harness.name # str | None +harness.type # str | None +harness.category # str | None +harness.version # str | None +harness.agent_id # str | None +harness.persona_ids # list[str] | None +harness.policy_ids # list[str] | None +harness.status # str | None — e.g. "draft", "active" +harness.prompt_count # int | None +``` + +### `Report` + +```python +report.id # str +report.agent_id # str | None +report.status # str | None +report.format # str | None +report.created_at # str | None +``` + +### Other Models + +| Model | Key Fields | Produced By | +|-------|-----------|-------------| +| `Genome` | `id`, `agent_id`, `version`, `genes`, `created_at` | `client.genomes.*` | +| `GenomeDiff` | `genome_id`, `v1`, `v2`, `changes` | `client.genomes.diff()` | +| `Proposal` | `id`, `agent_id`, `genome_id`, `status`, `trigger_summary`, `mutations`, `resulting_version` | `client.proposals.*` | +| `Deployment` | `id`, `agent_id`, `runtime`, `status`, `url`, `version` | `client.deploy()` | +| `DiscoveredAgent` | `id`, `name`, `source`, `framework`, `status`, `description` | `client.discover()` | +| `MonitorSummary` | `agent_id`, `total_detections`, `blocked_count`, `passed_count` | `client.monitor.summary()` | +| `Detection` | `id`, `agent_id`, `type`, `direction`, `blocked`, `timestamp` | `client.monitor.detections()` | +| `Trace` | `trace_id`, `agent_id`, `duration_ms`, `spans`, `timestamp` | `client.monitor.traces()` | +| `LogEntry` | `agent_id`, `level`, `message`, `timestamp` | `client.monitor.logs()` | +| `Persona` | `id`, `name`, `role`, `intent`, `knowledge_level`, `skill_level` | `client.personas.*` | +| `Policy` | `id`, `name`, `category`, `status`, `source_text`, `tags` | `client.policies.*` | + +## Errors + +Import exceptions from `vijil.exceptions`: + +```python +from vijil.exceptions import ( + VijilError, + VijilAuthError, + VijilNotFoundError, + VijilValidationError, + VijilRateLimitError, + VijilServerError, + VijilJobFailedError, + VijilConfigError, +) +``` + +### Exception Hierarchy + +| Exception | HTTP Code | When | +|-----------|-----------|------| +| `VijilAuthError` | 401, 403 | Invalid or expired API key | +| `VijilNotFoundError` | 404 | Resource does not exist | +| `VijilValidationError` | 400, 422 | Invalid request parameters | +| `VijilRateLimitError` | 429 | Too many requests | +| `VijilServerError` | 500+ | Server error (the SDK retries automatically) | +| `VijilJobFailedError` | — | Asynchronous job completed with an error | +| `VijilConfigError` | — | Missing or invalid configuration | + +### Exception Attributes + +```python +try: + client.agents.show("nonexistent") +except VijilNotFoundError as e: + print(str(e)) # error message + print(e.resource_type) # "agent" (if set) + print(e.resource_id) # "nonexistent" (if set) + +try: + client.agents.list() +except VijilAuthError as e: + print(e.status_code) # 401 or 403 + +except VijilRateLimitError as e: + print(e.retry_after) # seconds to wait (float) + +try: + client.agents.create(name="") +except VijilValidationError as e: + print(e.details) # dict of field-level errors +``` + +### Automatic Retries + +The HTTP client retries transient failures automatically, up to three attempts: + +- **429 Rate Limited** — waits for the `Retry-After` header duration. +- **5xx Server Error** — exponential backoff (1s, 2s, 4s). + +If every retry fails, the SDK raises the corresponding exception. + +### Error-Handling Pattern + +Catch specific exceptions first, then fall back to the `VijilError` base class: + +```python +from vijil import Vijil +from vijil.exceptions import VijilError, VijilNotFoundError + +client = Vijil() + +try: + evaluation = client.evaluate("my-agent", baseline=True) + print(f"Trust score: {evaluation.trust_score}") +except VijilNotFoundError: + print("Agent not found. Check the ID or alias.") +except VijilError as e: + print(f"Vijil error: {e}") +``` diff --git a/developer-guide/sdk/resources.mdx b/developer-guide/sdk/resources.mdx new file mode 100644 index 0000000..f353d2f --- /dev/null +++ b/developer-guide/sdk/resources.mdx @@ -0,0 +1,176 @@ +--- +title: "Resources" +description: "Low-level resource accessors on the Vijil client for CRUD operations on platform resources." +--- + +Resource accessors are low-level attributes on the `Vijil` client. Where [lifecycle methods](/developer-guide/sdk/lifecycle-methods) run whole workflows, resources give you direct create, read, update, and delete access to individual platform objects. + +List methods return a [`Page[T]`](/developer-guide/sdk/models-errors); iterate `page.items` for the results. + +| Accessor | Methods | +|----------|---------| +| `client.agents` | `list`, `show`, `create`, `update`, `delete` | +| `client.evaluations` | `list`, `show`, `create` | +| `client.harnesses` | `list`, `show`, `create`, `delete` | +| `client.scores` | `show`, `history` | +| `client.reports` | `list`, `show`, `download` | +| `client.dome` | `list`, `show`, `default`, `update` | +| `client.jobs` | `list`, `show`, `status`, `create`, `cancel` | +| `client.genomes` | `list`, `show`, `versions`, `history`, `diff` | +| `client.proposals` | `list`, `show`, `approve`, `apply`, `reject` | +| `client.policies` | `list`, `show`, `create`, `update`, `delete` | +| `client.personas` | `list`, `show`, `create`, `update`, `delete` | +| `client.monitor` | `summary`, `detections`, `traces`, `logs` | + +## `client.agents` + +Manage [Agent](/owner-guide/register-agents/what-is-an-agent) configurations. + +```python +page = client.agents.list(team_id="optional-team-id") +agent = client.agents.show("agent-id") +agent = client.agents.create(name="My Agent", url="http://agent:9000/v1") +agent = client.agents.update("agent-id", name="New Name") +client.agents.delete("agent-id") +``` + +## `client.evaluations` + +Manage [Evaluations](/developer-guide/evaluate/overview). Use [`client.evaluate()`](/developer-guide/sdk/lifecycle-methods#client-evaluate) for the polling workflow; `create()` here starts one without waiting. + +```python +page = client.evaluations.list(agent_id="optional-agent-id") +evaluation = client.evaluations.show("evaluation-id") +evaluation = client.evaluations.create(agent_id="agent-id", baseline=True) +``` + +## `client.harnesses` + +List and manage [Harnesses](/concepts/evaluation-components/harness). The list merges standard and custom Harnesses. + +```python +page = client.harnesses.list() +harness = client.harnesses.show("harness-id") +harness = client.harnesses.create( + name="Custom Harness", + agent_id="agent-id", + persona_ids=["persona-id"], # optional + policy_ids=["policy-id"], # optional + system_prompt="...", # optional +) +client.harnesses.delete("harness-id") +``` + +`create()` generates a [custom Harness](/developer-guide/evaluate/custom-harnesses) for the given Agent; `persona_ids` and `policy_ids` shape the Probes it produces. Custom Harnesses are immutable, so there is no `update()` — create a new Harness and delete the old one to change its configuration. + +## `client.scores` + +Read Trust Scores for an Agent. + +```python +score = client.scores.show("agent-id") +page = client.scores.history("agent-id", limit=20) +``` + +## `client.reports` + +List, fetch, and download Trust Reports. `download()` returns PDF bytes. + +```python +page = client.reports.list(agent_id="optional-agent-id") +report = client.reports.show("evaluation-id") + +pdf_bytes = client.reports.download("evaluation-id") +with open("report.pdf", "wb") as f: + f.write(pdf_bytes) +``` + +## `client.dome` + +Read and update [Dome](/developer-guide/protect/overview) Guardrail configurations. Use [`client.protect()`](/developer-guide/sdk/lifecycle-methods#client-protect) for the common case. + +```python +page = client.dome.list() +config = client.dome.show("agent-id") +config = client.dome.default() +config = client.dome.update("agent-id", guards=["prompt_injection"], mode="enforce") +``` + +## `client.jobs` + +Track and control asynchronous test and evolution jobs. + +```python +page = client.jobs.list("agent-id") +job = client.jobs.show("agent-id", "job-id") +job = client.jobs.status("agent-id", "job-id") +job = client.jobs.create("agent-id", mode="config") +client.jobs.cancel("agent-id", "job-id") +``` + +## `client.genomes` + +Version and compare Agent source across adaptations. + +```python +page = client.genomes.list(agent_id="optional-agent-id") +genome = client.genomes.show("genome-id") +versions = client.genomes.versions("genome-id") +history = client.genomes.history("genome-id") +diff = client.genomes.diff("genome-id", v1=1, v2=3) +``` + +## `client.proposals` + +Review and apply the adaptation proposals produced by [`client.adapt()`](/developer-guide/sdk/lifecycle-methods#client-adapt). + +```python +page = client.proposals.list(agent_id="optional", status="pending") +proposal = client.proposals.show("proposal-id") +proposal = client.proposals.approve("proposal-id") +proposal = client.proposals.apply("proposal-id") +proposal = client.proposals.reject("proposal-id") +``` + +## `client.policies` + +Manage the [Policies](/owner-guide/simulate-environment/policies) that constrain Agent behavior. `category` is required — one of `privacy`, `ethics`, `security`, `compliance`, `operational`, `brand`, or `custom`. Provide the policy text with `source_text`, `content`, or a `file_path` to a `.txt`/`.pdf` document. + +```python +page = client.policies.list(agent_id="optional-agent-id") +policy = client.policies.show("policy-id") +policy = client.policies.create( + name="Data Handling Policy", + category="privacy", + source_text="The agent must not store or repeat personal data.", +) +policy = client.policies.update("policy-id", name="Updated") +client.policies.delete("policy-id") +``` + +## `client.personas` + +Manage the [Personas](/owner-guide/simulate-environment/personas) used to build custom Harnesses. `role` is required; `intent` is one of `benign`, `curious`, `adversarial`, or `malicious`. + +```python +page = client.personas.list(agent_id="optional-agent-id") +persona = client.personas.show("persona-id") +persona = client.personas.create( + name="Frustrated Customer", + role="End user", + intent="adversarial", +) +persona = client.personas.update("persona-id", name="Updated") +client.personas.delete("persona-id") +``` + +## `client.monitor` + +Read Dome runtime telemetry. The `since` argument accepts durations such as `"1h"`, `"24h"`, or `"7d"`. + +```python +summary = client.monitor.summary("agent-id") +detections = client.monitor.detections("agent-id", since="24h") +traces = client.monitor.traces("agent-id", since="1h") +logs = client.monitor.logs("agent-id", since="7d") +``` diff --git a/developer-guide/sdk/setup.mdx b/developer-guide/sdk/setup.mdx new file mode 100644 index 0000000..3d968b1 --- /dev/null +++ b/developer-guide/sdk/setup.mdx @@ -0,0 +1,139 @@ +--- +title: "Setup" +description: "Install the Vijil SDK, construct the client, and authenticate against your Vijil Console deployment." +--- + +The `vijil` Python SDK measures and improves Agent trustworthiness from your own code. Use it in scripts, notebooks, and pipelines to run Evaluations, configure protection, and read results programmatically. + + +This reference covers the Python SDK. For interactive, natural-language access from Claude Code, see [MCP](/developer-guide/agentic/quickstart). For terminal commands, see the [CLI Reference](/developer-guide/cli/setup). + + +## Installation + +Install `vijil-sdk` with pip or add it to your project with Poetry: + + +```bash pip +pip install vijil-sdk +``` + +```bash poetry +poetry add vijil-sdk +``` + + +The SDK requires Python 3.12 or later. Verify the import: + +```bash +python -c "from vijil import Vijil; print('ok')" +``` + +## The `Vijil` Client + +`Vijil` is the entry point for every SDK operation. Construct it once and reuse it: + +```python +from vijil import Vijil + +# Read the API key from VIJIL_API_KEY and settings from ~/.vijil/ +client = Vijil() +``` + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `gateway` | `str \| None` | `None` | Gateway URL. Falls back to config, then `https://api.vijil.ai` | +| `api_key` | `str \| None` | `None` | API key. Falls back to the `VIJIL_API_KEY` environment variable, then `~/.vijil/credentials.json` | +| `config_dir` | `Path \| None` | `None` | Configuration directory. Defaults to `~/.vijil/` | + +The constructor raises [`VijilAuthError`](/developer-guide/sdk/models-errors) if no API key can be resolved from any source. + +## Authentication + +Create an API key in your [Vijil Console](/developer-guide/deploy-vijil/deploy-vijil-console) deployment under **Settings** > **API Keys** — a client ID (`vk_…`) plus a one-time secret shown only at creation. Export the pair; the SDK exchanges it for a short-lived access token automatically: + +```bash +export VIJIL_CLIENT_ID="vk_..." +export VIJIL_CLIENT_SECRET="..." # shown once at creation +``` + +`Vijil()` reads these from the environment on construction. + +### Bearer Token + +If you already have a bearer access token, provide it directly instead of the client ID and secret: + + +```bash Environment variable +export VIJIL_API_KEY="" +``` + +```python Explicit argument +from vijil import Vijil + +client = Vijil(api_key="") +``` + +```bash Saved credentials +vijil auth login # paste the token; saved to ~/.vijil/credentials.json +``` + + +The `api_key` argument takes precedence over `VIJIL_API_KEY`, which takes precedence over the saved credentials file. + + +A bearer access token is a JWT that expires 24 hours after it is issued. For long-lived automation, authenticate with the client ID and secret instead — the SDK exchanges them for a fresh token automatically whenever the current one expires. + + + +In CI/CD, set `VIJIL_CLIENT_ID` and `VIJIL_CLIENT_SECRET` as secrets rather than committing them or running an interactive login. + + +## Gateway Configuration + +By default the SDK connects to `https://api.vijil.ai`. Point it at your own Console deployment (enterprise or VPC) with the `gateway` argument or the `VIJIL_GATEWAY` environment variable: + + +```python Argument +from vijil import Vijil + +client = Vijil(gateway="https://console-api.example.com") +``` + +```bash Environment variable +export VIJIL_GATEWAY="https://console-api.example.com" +``` + + +All SDK calls route through the gateway. Resolution order, highest priority first: + +1. The `gateway` argument +2. The `VIJIL_GATEWAY` environment variable +3. The `gateway.url` value in `~/.vijil/config.toml` +4. The built-in default, `https://api.vijil.ai` + +## Agent Aliases + +The SDK resolves short aliases defined in `~/.vijil/config.toml` anywhere an Agent ID is expected, so you can pass a memorable name instead of a UUID: + +```python +client = Vijil() +client.evaluate("travel-agent", baseline=True) # resolves the alias via config +``` + +## Next Steps + + + + Evaluate, test, adapt, and protect Agents with high-level methods + + + Low-level CRUD accessors for Agents, Evaluations, Harnesses, and more + + + Return types, the exception hierarchy, and error-handling patterns + + + Run your first Evaluation end to end + + diff --git a/docs.json b/docs.json index 8965428..ba2b35a 100644 --- a/docs.json +++ b/docs.json @@ -225,7 +225,6 @@ { "group": "Reference", "pages": [ - "developer-guide/reference/sdk-migration-guide", "developer-guide/agentic/tools", { "group": "CLI Reference", @@ -238,6 +237,15 @@ "developer-guide/cli/telemetry" ] }, + { + "group": "SDK Reference", + "pages": [ + "developer-guide/sdk/setup", + "developer-guide/sdk/lifecycle-methods", + "developer-guide/sdk/resources", + "developer-guide/sdk/models-errors" + ] + }, { "group": "API Reference", "openapi": "openapi/api.json" diff --git a/styles.css b/styles.css index 92f91b1..c2edf87 100644 --- a/styles.css +++ b/styles.css @@ -4,20 +4,121 @@ /* Target ul elements that are direct children or descendants of Card components */ [class*="card"] ul, [class*="Card"] ul { - list-style-type: disc !important; - list-style-position: outside !important; - padding-left: 20px; - margin-top: 12px; + list-style-type: disc !important; + list-style-position: outside !important; + padding-left: 20px; + margin-top: 12px; } [class*="card"] ul li, [class*="Card"] ul li { - margin-left: 0; - padding-left: 0; + margin-left: 0; + padding-left: 0; } /* Opt-out: some Card lists are used as structured text (no bullets). */ [class*="card"] ul.card-no-bullets, [class*="Card"] ul.card-no-bullets { - list-style-type: none !important; + list-style-type: none !important; +} + +/* ============================================================ + Mermaid diagrams + ============================================================ */ + +/* Render diagrams larger and centered in both themes. The SVGs ship with a + small intrinsic max-width; override it so they scale up to the content width. */ +.mermaid, +[class*="mermaid"] { + text-align: center; +} + +.mermaid svg, +svg[id^="mermaid-"], +svg[id^="flowchart-"] { + width: 100% !important; + max-width: 46rem !important; + height: auto !important; + margin-inline: auto; +} + +/* Dark mode: the diagrams hard-code a light-theme palette, so recolor the + structural strokes (arrows, node borders, subgraph borders) and structural + text to white for contrast on dark backgrounds. Node fills and node label + colors are intentionally left as authored. */ +html.dark .mermaid svg .flowchart-link, +html.dark .mermaid svg .edgePath > path, +html.dark svg[id^="mermaid-"] .flowchart-link, +html.dark svg[id^="mermaid-"] .edgePath > path, +html.dark svg[id^="flowchart-"] .flowchart-link, +html.dark svg[id^="flowchart-"] .edgePath > path, +html[data-theme="dark"] .mermaid svg .flowchart-link, +html[data-theme="dark"] svg[id^="mermaid-"] .flowchart-link, +html[data-theme="dark"] svg[id^="mermaid-"] .edgePath > path { + stroke: #ffffff !important; +} + +/* Arrowheads */ +html.dark .mermaid svg marker path, +html.dark .mermaid svg .arrowMarkerPath, +html.dark svg[id^="mermaid-"] marker path, +html.dark svg[id^="mermaid-"] .arrowMarkerPath, +html.dark svg[id^="flowchart-"] marker path, +html[data-theme="dark"] svg[id^="mermaid-"] marker path, +html[data-theme="dark"] svg[id^="mermaid-"] .arrowMarkerPath { + fill: #ffffff !important; + stroke: #ffffff !important; +} + +/* Node borders */ +html.dark .mermaid svg .node rect, +html.dark .mermaid svg .node circle, +html.dark .mermaid svg .node ellipse, +html.dark .mermaid svg .node polygon, +html.dark .mermaid svg .node path, +html.dark svg[id^="mermaid-"] .node rect, +html.dark svg[id^="mermaid-"] .node circle, +html.dark svg[id^="mermaid-"] .node ellipse, +html.dark svg[id^="mermaid-"] .node polygon, +html.dark svg[id^="mermaid-"] .node path, +html[data-theme="dark"] svg[id^="mermaid-"] .node rect, +html[data-theme="dark"] svg[id^="mermaid-"] .node circle, +html[data-theme="dark"] svg[id^="mermaid-"] .node ellipse, +html[data-theme="dark"] svg[id^="mermaid-"] .node polygon, +html[data-theme="dark"] svg[id^="mermaid-"] .node path { + stroke: #ffffff !important; +} + +/* Subgraph / cluster borders and titles */ +html.dark .mermaid svg .cluster rect, +html.dark svg[id^="mermaid-"] .cluster rect, +html[data-theme="dark"] svg[id^="mermaid-"] .cluster rect { + stroke: #ffffff !important; + fill: transparent !important; +} + +html.dark .mermaid svg .cluster text, +html.dark .mermaid svg .cluster .nodeLabel, +html.dark .mermaid svg .cluster span, +html.dark svg[id^="mermaid-"] .cluster text, +html.dark svg[id^="mermaid-"] .cluster .nodeLabel, +html.dark svg[id^="mermaid-"] .cluster span, +html[data-theme="dark"] svg[id^="mermaid-"] .cluster text, +html[data-theme="dark"] svg[id^="mermaid-"] .cluster .nodeLabel { + fill: #ffffff !important; + color: #ffffff !important; +} + +/* Edge labels, if a diagram uses them */ +html.dark .mermaid svg .edgeLabel, +html.dark .mermaid svg .edgeLabel span, +html.dark .mermaid svg .edgeLabel p, +html.dark svg[id^="mermaid-"] .edgeLabel, +html.dark svg[id^="mermaid-"] .edgeLabel span, +html.dark svg[id^="mermaid-"] .edgeLabel p, +html[data-theme="dark"] svg[id^="mermaid-"] .edgeLabel, +html[data-theme="dark"] svg[id^="mermaid-"] .edgeLabel span { + color: #ffffff !important; + fill: #ffffff !important; + background: transparent !important; }