docs: install matrix, telemetry opt-out, and runnable root quickstarts #2666

Feature Request

Make the root README a trustworthy first install: package extras matrix, telemetry opt-out before import, runnable quickstarts, and a short concepts blurb (Scenario / Check / Suite / Target).

Motivation

pip install giskard only pulls checks; scan and provider SDKs are extras. Telemetry opt-out lives in giskard-core but not on the landing path (and must be set before import). Scan quickstart uses undefined my_agent. Checks snippets often omit asyncio.run.

Implementation plan

1. Edit root README.md Install + Checks + Scan sections only (minimal churn).
2. Add extras table + telemetry blurb linking to libs/giskard-core/README.md.
3. Rewrite Checks fence with async def main + asyncio.run(main()).
4. Rewrite Scan fence with a real stub target.
5. Add a short Concepts subsection.
6. Cross-link giskard[scan] / provider extras next to judge usage — no package README rewrite.

Suggested README fragments

Install

## Install

```sh
pip install giskard           # checks (+ agents, llm, core)
pip install "giskard[scan]"   # + vulnerability / quality scan
pip install "giskard[openai]" # provider SDK for LLM judges / generators

Telemetry: optional aggregated analytics via giskard-core. No prompts or outputs are sent.
Opt out before importing Giskard: export DO_NOT_TRACK=1 or GISKARD_TELEMETRY_DISABLED=1.
Details: giskard-core README.

**Concepts**

```markdown
### Concepts

- **Target** — your system under test: any sync/async callable `(inputs) -> outputs` (optionally with `trace`)
- **Scenario** — one eval: interactions + checks
- **Check** — assertion or LLM judge over the trace
- **Suite** — many scenarios run together

`giskard.agents.Generator` is an LLM client for workflows/judges — not the same as
`giskard.checks` input generators (`LLMGenerator`) that synthesize user messages.

Checks quickstart shape

import asyncio
from giskard.checks import Scenario, Groundedness

def get_answer(inputs: str) -> str:
    return "Paris"  # replace with your model / agent

async def main() -> None:
    scenario = (
        Scenario("test_france_capital")
        .interact(inputs="What is the capital of France?", outputs=get_answer)
        .check(
            Groundedness(
                name="answer is grounded",
                context="France is in Western Europe. Its capital is Paris.",
            )
        )
    )
    result = await scenario.run()
    result.print_report()

asyncio.run(main())

Scan quickstart shape

import asyncio
from giskard.scan import vulnerability_scan

async def my_agent(inputs: str) -> str:
    # Replace with your agent / model call
    return f"Echo: {inputs}"

async def main() -> None:
    await vulnerability_scan(
        target=my_agent,
        description="A customer support chatbot for an e-commerce platform.",
        languages=["en"],
    )

asyncio.run(main())

Acceptance criteria

• Extras matrix + telemetry “before import” + core link
• Checks quickstart pasteable with asyncio.run
• Scan quickstart defines a concrete target
• Concepts blurb includes Target and the Generator collision sentence

Out of scope

• Full package README rewrites
• Examples CI gate (separate)
• v2/v3 mapping (docs(readme): correct v2/v3 feature mapping — RAG now in giskard-scan #2610)
• Error type collapse (separate)