Metadata-Version: 2.4
Name: traigent
Version: 0.18.1.dev10
Summary: Enterprise-grade LLM optimization platform with advanced analytics and AI-powered insights
Author-email: Traigent Team <opensource@traigent.ai>
License-Expression: AGPL-3.0-only OR LicenseRef-Traigent-Commercial
Project-URL: Homepage, https://github.com/Traigent/Traigent
Project-URL: Documentation, https://docs.traigent.ai
Project-URL: Repository, https://github.com/Traigent/Traigent
Project-URL: Bug Tracker, https://github.com/Traigent/Traigent/issues
Project-URL: Changelog, https://github.com/Traigent/Traigent/blob/main/CHANGELOG.md
Keywords: llm,optimization,machine-learning,ai,hyperparameter-tuning,analytics,meta-learning,cost-optimization,anomaly-detection,predictive-analytics,enterprise,bayesian-optimization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: COMMERCIAL-LICENSE.md
License-File: CONTRIBUTOR-LICENSING.md
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=12.0.0
Requires-Dist: aiohttp<4.0,>=3.14.0
Requires-Dist: requests>=2.33.0
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: cryptography>=46.0.7
Requires-Dist: PyJWT[crypto]<3.0.0,>=2.13.0
Requires-Dist: backoff>=2.2.0
Requires-Dist: litellm<2,>=1.87.1
Requires-Dist: rank-bm25
Requires-Dist: psutil>=5.8.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: analytics
Requires-Dist: numpy>=1.21.0; extra == "analytics"
Requires-Dist: pandas>=1.3.0; extra == "analytics"
Requires-Dist: matplotlib>=3.5.0; extra == "analytics"
Provides-Extra: bayesian
Requires-Dist: scikit-learn>=1.0.0; extra == "bayesian"
Requires-Dist: scipy>=1.7.0; extra == "bayesian"
Provides-Extra: integrations
Requires-Dist: langchain>=0.0.200; extra == "integrations"
Requires-Dist: langchain-core>=1.2.28; extra == "integrations"
Requires-Dist: langchain-community>=0.3.27; extra == "integrations"
Requires-Dist: langchain-anthropic>=0.2.0; extra == "integrations"
Requires-Dist: langchain-openai>=1.1.14; extra == "integrations"
Requires-Dist: langchain-text-splitters>=0.3.8; extra == "integrations"
Requires-Dist: langchain-google-genai>=2.1.4; extra == "integrations"
Requires-Dist: openai>=2.0.0; extra == "integrations"
Requires-Dist: anthropic>=0.18.0; extra == "integrations"
Requires-Dist: groq>=0.9.0; extra == "integrations"
Requires-Dist: google-genai>=0.8.0; extra == "integrations"
Requires-Dist: google-generativeai>=0.3.0; extra == "integrations"
Requires-Dist: rank_bm25>=0.2.2; extra == "integrations"
Requires-Dist: mlflow<4.0,>=3.11.1; extra == "integrations"
Requires-Dist: wandb>=0.15.0; extra == "integrations"
Requires-Dist: python-dotenv>=1.2.2; extra == "integrations"
Requires-Dist: boto3>=1.28.0; extra == "integrations"
Requires-Dist: botocore>=1.31.0; extra == "integrations"
Requires-Dist: faiss-cpu>=1.7.0; sys_platform != "win32" and extra == "integrations"
Provides-Extra: chroma
Requires-Dist: langchain-chroma>=0.2.5; extra == "chroma"
Provides-Extra: dspy
Requires-Dist: dspy-ai>=2.5.0; extra == "dspy"
Provides-Extra: pydanticai
Requires-Dist: pydantic-ai-slim<2,>=1.56.0; extra == "pydanticai"
Provides-Extra: security
Requires-Dist: passlib>=1.7.4; extra == "security"
Requires-Dist: python-multipart>=0.0.26; extra == "security"
Requires-Dist: fastapi>=0.95.0; extra == "security"
Requires-Dist: starlette>=0.49.1; extra == "security"
Requires-Dist: uvicorn>=0.18.0; extra == "security"
Requires-Dist: redis>=4.0.0; extra == "security"
Requires-Dist: defusedxml>=0.7.1; extra == "security"
Requires-Dist: pyotp>=2.9.0; extra == "security"
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.5.0; extra == "visualization"
Requires-Dist: plotly>=5.0.0; extra == "visualization"
Provides-Extra: hybrid
Requires-Dist: httpx[http2]>=0.24.0; extra == "hybrid"
Requires-Dist: claude-code-sdk>=0.0.14; extra == "hybrid"
Requires-Dist: mcp>=1.27.0; extra == "hybrid"
Provides-Extra: mcp
Requires-Dist: mcp>=1.27.0; extra == "mcp"
Provides-Extra: internal-schema
Requires-Dist: traigent-schema==4.1.0; extra == "internal-schema"
Provides-Extra: test
Requires-Dist: pytest>=9.0.3; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Requires-Dist: pytest-timeout>=2.0.0; extra == "test"
Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
Requires-Dist: coverage>=7.0.0; extra == "test"
Requires-Dist: rapidfuzz>=3.14.0; extra == "test"
Requires-Dist: hypothesis>=6.0.0; extra == "test"
Provides-Extra: tracing
Requires-Dist: opentelemetry-api<2.0.0,>=1.20.0; extra == "tracing"
Requires-Dist: opentelemetry-sdk<2.0.0,>=1.20.0; extra == "tracing"
Requires-Dist: opentelemetry-exporter-otlp<2.0.0,>=1.20.0; extra == "tracing"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: black>=26.3.1; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
Requires-Dist: types-requests>=2.31.0; extra == "dev"
Requires-Dist: types-bleach>=6.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: bandit>=1.7.0; extra == "dev"
Requires-Dist: hypothesis>=6.100.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.4.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.22.0; extra == "docs"
Provides-Extra: ml
Requires-Dist: traigent[analytics,bayesian]; extra == "ml"
Requires-Dist: numpy>=1.21.0; extra == "ml"
Requires-Dist: scipy>=1.7.0; extra == "ml"
Provides-Extra: deepeval
Requires-Dist: deepeval>=1.0.0; extra == "deepeval"
Provides-Extra: cloud
Requires-Dist: traigent[security]; extra == "cloud"
Requires-Dist: boto3>=1.28.0; extra == "cloud"
Provides-Extra: recommended
Requires-Dist: traigent[analytics,bayesian,hybrid,integrations,pydanticai,visualization]; extra == "recommended"
Provides-Extra: all
Requires-Dist: traigent[analytics,bayesian,hybrid,integrations,pydanticai,security,test,tracing,visualization]; extra == "all"
Provides-Extra: enterprise
Requires-Dist: traigent[analytics,bayesian,cloud,hybrid,integrations,ml,security,test,tracing,visualization]; extra == "enterprise"
Dynamic: license-file

# Traigent

<p align="center">
  <a href="https://github.com/Traigent/Traigent/actions/workflows/tests.yml"><img src="https://github.com/Traigent/Traigent/actions/workflows/tests.yml/badge.svg" alt="CI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL_v3-blue.svg" alt="License: AGPL-3.0"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+"></a>
  <a href="docs/getting-started/GETTING_STARTED.md"><img src="https://img.shields.io/badge/docs-getting%20started-brightgreen.svg" alt="Docs"></a>
</p>

**Traigent is an AI Agent infrastructure that allows companies to take AI agents out of the lab and deploy them at high scale with high confidence.**

Our mission: **Anything you can measure, we can improve.** Whether it's accuracy, speed of response, cost, or any other business metric — we bring strong results that deliver real business value.

> **Runs multiple LLM trials** — run `python -m traigent.examples.quickstart` for a no-cost demo, or call `enable_mock_mode_for_quickstart()` from `traigent.testing` in local tutorial code. Set `TRAIGENT_RUN_COST_LIMIT=2.0` as a best-effort local guardrail and set hard caps with your LLM/cloud providers; actual billing is determined by those providers. The legacy `TRAIGENT_MOCK_LLM=true` env var remains for backwards compatibility and is disabled when `ENVIRONMENT=production`. See [Cost Management](#cost-management).

**Quick Install:**

Install from PyPI — no clone required (Python 3.11+):

```bash
# pip
pip install "traigent[recommended]"

# uv (into the active venv, or `uv add` into a uv project)
uv pip install "traigent[recommended]"
uv add "traigent[recommended]"
```

<details>
<summary>Prefer an isolated virtual environment first?</summary>

macOS / Linux:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install "traigent[recommended]"
```

Windows PowerShell:

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install "traigent[recommended]"
```

</details>

For more options, see [Installation details](#installation).

**Try it now - no API keys needed:**

```bash
pip install "traigent[integrations]"
python -m traigent.examples.quickstart
```

Or from a source checkout:

```bash
python hello_world.py
```

**Here's what the quickstart does - one decorator, automatic optimization:**

```python
from langchain_openai import ChatOpenAI
import traigent

@traigent.optimize(
    configuration_space={
        "model": ["gpt-4o-mini", "gpt-4o"],
        "temperature": [0.0, 0.7, 1.0],
    },
    objectives=["accuracy"],
    eval_dataset="qa_samples.jsonl",
)
def answer(question: str) -> str:
    cfg = traigent.get_config()
    llm = ChatOpenAI(model=cfg["model"], temperature=cfg["temperature"])
    return llm.invoke(question).content
```

---

## Using it in your own code

Add `@traigent.optimize()` to any function that calls an LLM — no framework required:

```python
import traigent
import litellm                    # or openai, anthropic, requests …

@traigent.optimize(
    configuration_space={
        "model": ["gpt-4o-mini", "gpt-4o"],
        "temperature": [0.0, 0.7, 1.0],
    },
    objectives=["accuracy"],
    eval_dataset="path/to/your_evals.jsonl",
)
def your_function(question: str) -> str:
    cfg = traigent.get_config()
    response = litellm.completion(
        model=cfg["model"],
        temperature=cfg["temperature"],
        messages=[{"role": "user", "content": question}],
    )
    return response.choices[0].message.content
```

Works with any LLM provider — [OpenAI](https://platform.openai.com/docs), [Anthropic](https://docs.anthropic.com), [LiteLLM](https://github.com/BerriAI/litellm) (100+ providers), or plain HTTP calls.

<p align="center">
  <a href="https://portal.traigent.ai">Portal</a> &middot;
  <a href="docs/getting-started/GETTING_STARTED.md">Quickstart</a> &middot;
  <a href="examples/">Examples</a> &middot;
  <a href="docs/agent-skill.md">Skill</a> &middot;
  <a href="docs/walkthrough.md">Walkthrough</a>
</p>

---

## Choose Your Path

| Goal | Resource | Time |
|------|----------|------|
| **Get started quickly** | [Quick Start Guide](docs/getting-started/GETTING_STARTED.md) | 5 min |
| **Understand the architecture** | [Architecture Overview](docs/architecture/ARCHITECTURE.md) | 5 min |
| **Track runs in the portal** | [Portal tracking](#portal-tracking) | 5 min |
| **Try examples locally, then make runs portal-visible** | [Mock walkthrough](walkthrough/mock/) (8 steps) → [Portal](https://portal.traigent.ai) | 15 min |
| **Read the full API reference** | [Decorator Reference →](docs/api-reference/decorator-reference.md) | — |

<details>
<summary>Full documentation index</summary>

| | |
| --- | --- |
| **Get started** | [Installation](docs/getting-started/installation.md) · [5-minute tutorial](docs/getting-started/GETTING_STARTED.md) |
| **User guides** | [Injection Modes](docs/user-guide/injection_modes.md) · [Configuration Spaces](docs/user-guide/configuration-spaces.md) · [Evaluation](docs/user-guide/evaluation_guide.md) |
| **Tunable Variable Language** | [TVL Guide](docs/user-guide/tuned_variables.md) |
| **Advanced** | [Agent Optimization](docs/user-guide/agent_optimization.md) |
| **API reference** | [Decorator Reference](docs/api-reference/decorator-reference.md) · [Constraint DSL](docs/features/constraint-dsl.md) |

</details>

---

<details>
<summary>🎬 See Traigent in Action — click to play demos</summary>

| Demo | |
|------|-|
| **LLM Agent Optimization** | [![Optimization Demo](docs/demos/output/optimize-still.svg)](docs/demos/output/optimize.svg) |
| **Optimization Callbacks** | [![Callbacks Demo](docs/demos/output/hooks-still.svg)](docs/demos/output/hooks.svg) |
| **Agent Configuration Hooks** | [![Agent Hooks Demo](docs/demos/output/github-hooks-still.svg)](docs/demos/output/github-hooks.svg) |

</details>

<a id="architecture-overview"></a>

<details>
<summary>🏗️ Architecture Overview — how it works</summary>

1. **Suggest** — the optimizer proposes a configuration to test
2. **Inject** — Traigent overrides your function's parameters with the proposed config
3. **Evaluate** — your function runs against the dataset, scored by the evaluator
4. **Record** — results update the optimizer's model
5. **Repeat** — loop continues until budget/trials exhausted, then outputs results

![Architecture Overview](docs/demos/output/architecture.svg)

**[Read the full architecture guide →](docs/architecture/ARCHITECTURE.md)**

</details>

---

## 🚀 Walkthrough — 8 runnable examples

The walkthrough examples use local mock mode through the quickstart/testing helpers with cost approval pre-set for dry runs — no provider API keys needed when calls go through LiteLLM or LangChain.

<details>
<summary>Show all 8 walkthrough steps</summary>

| # | Run | What you'll learn |
|---|-----|-------------------|
| 1 | `python walkthrough/mock/01_tuning_qa.py` | Basic model + temperature optimization |
| 2 | `python walkthrough/mock/02_zero_code_change.py` | Seamless mode — zero code changes to existing code |
| 3 | `python walkthrough/mock/03_parameter_mode.py` | Explicit config access via `traigent.get_config()` |
| 4 | `python walkthrough/mock/04_multi_objective.py` | Balance accuracy, cost, and latency |
| 5 | `python walkthrough/mock/05_rag_parallel.py` | RAG optimization with parallel evaluation |
| 6 | `python walkthrough/mock/06_custom_evaluator.py` | Define your own success metrics |
| 7 | `python walkthrough/mock/07_multi_provider.py` | Compare OpenAI, Anthropic, Google in one run |
| 8 | `python walkthrough/mock/08_privacy_modes.py` | No-egress local execution |

</details>

**[Browse reference examples →](examples/) · [Injection modes →](docs/user-guide/injection_modes.md)**

---

<a id="portal-tracking"></a>

### ☁️ Traigent Portal Tracking

Connect to [Traigent Portal](https://portal.traigent.ai) to view results, compare trials, and collaborate. Portal tracking is enabled automatically when `TRAIGENT_API_KEY` is set; most users do not need any routing settings.

The default run uses Traigent's smart optimizer when portal credentials are available. Local `grid` and `random` searches still sync results to the portal when authenticated. Use `offline=True` only when a run must avoid Traigent backend egress; offline runs do not sync.

1. **Sign up** at [portal.traigent.ai](https://portal.traigent.ai) — verify your email to activate
2. **Create an API key** — click your name (top-right) → **API Keys** → **+ Create API Key**
3. **Connect** — run `traigent auth login` or set `export TRAIGENT_API_KEY=”sk_...”`  <!-- pragma: allowlist secret -->
4. **Run** — portal tracking is automatic

<details>
<summary>Credential priority and multi-provider setup</summary>

| Credential  | 1st (highest)                  | 2nd                    | 3rd (default)        |
|-------------|--------------------------------|------------------------|----------------------|
| API Key     | `TRAIGENT_API_KEY` env var     | Stored CLI credentials | None (local only)    |
| Backend URL | `TRAIGENT_BACKEND_URL` env var | Stored CLI credentials | `portal.traigent.ai` |

> **Tip:** No env vars needed after `traigent auth login` — the SDK picks up stored credentials automatically.

**Multi-provider optimization** — use [LiteLLM](https://github.com/BerriAI/litellm) to compare OpenAI, Anthropic, Google, Mistral, and 100+ providers:

```python
@traigent.optimize(
    configuration_space={
        "model": ["gpt-4o-mini", "claude-haiku-4-5-20251001", "gemini/gemini-pro"],
        "temperature": [0.1, 0.5, 0.9],
    },
    objectives=["accuracy", "cost"],
    eval_dataset="data/qa_samples.jsonl",
)
def multi_provider_agent(question: str) -> str:
    config = traigent.get_config()
    response = litellm.completion(
        model=config.get("model"),
        temperature=config.get("temperature"),
        messages=[{"role": "user", "content": question}],
    )
    return response.choices[0].message.content
```

</details>

---

## ✨ Key Features

| Feature | Description |
|---------|-------------|
| **Zero-code integration** | Add `@traigent.optimize()` to existing code — no refactoring |
| **Multi-algorithm** | Random and Grid locally; Bayesian (TPE, NSGA-II, CMA-ES) via the Traigent cloud |
| **Multi-objective** | Optimize accuracy, latency, cost, and custom metrics simultaneously |
| **Framework support** | LangChain, OpenAI SDK, Anthropic, LiteLLM, and any LLM provider |
| **Cost tracking** | Integrated tokencost library with 500+ model pricing |
| **Parallel execution** | Concurrent trials and example-level parallelism |
| **Error resilience** | Interactive pause on rate limits and budget caps — resume or stop gracefully |
| **Live progress** | Auto-enabled progress bar in interactive terminals (`progress_bar=False` to disable) |
| **No-egress option** | `offline=True` keeps Traigent optimization traffic local when policy requires it |

**TraigentDemo** — Streamlit playground, use cases, and research benchmarks

---

<details>
<summary>📦 Installation details, optimization routing, CLI, and more</summary>

### Installation

Python 3.11+ on Linux, macOS, or Windows. The published package on [PyPI](https://pypi.org/project/traigent/) is the recommended way to install — `pip install "traigent[recommended]"` or `uv add "traigent[recommended]"`. No repository checkout is required to use the SDK or its `traigent` CLI.

| Feature Set | Description |
|-------------|-------------|
| `[recommended]` | All user-facing features (default) |
| `[integrations]` | LangChain, OpenAI, Anthropic adapters |
| `[analytics]` | Visualization and analytics |
| `[bayesian]` | Bayesian optimization dependencies (used by the Traigent cloud; not available locally) |
| `[all]` | Everything |

**[Full installation guide →](docs/getting-started/installation.md)**

Contributor / source install (only needed to hack on Traigent itself or run the
coordinated release-validation suite — not required to use the SDK):

```bash
git clone https://github.com/Traigent/Traigent.git
cd Traigent
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[recommended]"
```

### Cost Management

| Setting | How |
|---------|-----|
| Testing (no API calls) | Import and call `enable_mock_mode_for_quickstart()` from `traigent.testing`, or run `python -m traigent.examples.quickstart` for the demo |
| Cost Limit | `TRAIGENT_RUN_COST_LIMIT=2.0` (default: $2/run) |

Cost estimates, budgets, limits, alerts, and thresholds are best-effort software controls, not
provider-side billing guarantees. Actual billing is determined by your LLM/cloud providers, and you
remain responsible for provider charges. The legacy `TRAIGENT_MOCK_LLM=true` env var is supported
only for backwards-compatible local scripts and is disabled when `ENVIRONMENT=production`.
Mock mode skips the optimized-function pricing preflight for supported calls made through
Traigent's integration/interceptor path; direct provider calls made outside that path should
be stubbed explicitly for a guaranteed $0 rehearsal. See [DISCLAIMER.md](DISCLAIMER.md)
for details.

### Evaluation

Provide a JSONL dataset — Traigent scores outputs by exact / case-insensitive match by default. For semantic scoring (paraphrases, summarization, translation), supply a `scoring_function` (embeddings or LLM-judge) or a `custom_evaluator`:

```jsonl
{"input": {"question": "What is AI?"}, "output": "Artificial Intelligence"}
{"input": {"question": "Explain ML"}, "output": "Machine learning uses data and algorithms"}
```

- `input` (required): your function's parameter names as keys
- `output` (optional): expected output for accuracy scoring

**[Evaluation guide →](docs/guides/evaluation.md)** — custom evaluators, dataset formats, troubleshooting

### Optimization Routing

| Request | Where optimization decisions come from | Portal sync |
|------|--------|---------|
| Omit routing settings | Traigent smart optimizer when authenticated | Yes |
| `algorithm="grid"` or `"random"` | Local search in your Python process | Yes, unless `offline=True` |
| Smart algorithm name, such as `"bayesian"` or `"optuna_tpe"` | Traigent cloud optimizer | Yes |
| `offline=True` | Local only, zero Traigent backend egress | No |

Most users should omit these settings. Use `grid` or `random` for explicit local search; use `offline=True` only for no-egress runs.

**[Optimization routing guide →](docs/guides/execution-modes.md)** — defaults, local search, portal sync, and migration notes

### Quick Reference

| Parameter | Where | Description |
|-----------|-------|-------------|
| `configuration_space` | `@traigent.optimize()` | Parameters to test (required) |
| `objectives` | `@traigent.optimize()` | Metrics to optimize for |
| `eval_dataset` | `@traigent.optimize()` | Dataset for evaluation |
| `algorithm` | `.optimize()` call | `"random"`, `"grid"` (local); smart algorithms run in the Traigent cloud |
| `max_trials` | `.optimize()` call | Number of configurations to test |
| `progress_bar` | `.optimize()` call | `True` / `False` / `None` (auto) — live progress bar |

### Injection Modes

| Mode | Best for | How |
|------|----------|-----|
| **Context** (default) | Most cases | Inside the decorated function, call `traigent.get_config()` to read the active configuration (`config.get("key", default)`). |
| **Seamless** | Existing functions with simple local config defaults | Pass `injection_mode="seamless"`; Traigent rewrites simple local variable assignments that match configuration keys. |
| **Parameter** | New development | Pass `injection_mode="parameter"`; the decorated function receives a `config` argument with explicit `config.get("key")` access. |

**[Injection modes guide →](docs/user-guide/injection_modes.md)**

### CLI

```bash
traigent optimize module.py -a grid -n 10   # Run optimization
traigent validate data.jsonl -o accuracy     # Validate dataset
traigent results                             # List past runs
traigent plot <name> -p progress             # Visualize results
traigent auth login                          # Authenticate with portal
traigent --help                              # Full command reference
```

### Troubleshooting

| Problem | Fix |
|---------|-----|
| `ModuleNotFoundError` | `pip install -e ".[recommended]"` or check venv is activated |
| 0.0% accuracy | Check dataset format; for local demos, import and call `enable_mock_mode_for_quickstart()` from `traigent.testing` |
| Missing API keys | Copy `.env.example` to `.env`; or run `python -m traigent.examples.quickstart` for a no-key demo |
| `pytest` rejects `-n` / `--dist` | Install dev test tooling first: `pip install -e ".[all,dev]"` |
| `execution={"runtime": "node"}` fails | Python SDK 0.12.0 removed the temporary JS bridge. Use native `@traigent/sdk`; see [JS bridge migration](docs/guides/js-bridge.md). |
| Permission errors | Create a fresh venv and reinstall dependencies |

</details>

---

## 🛠️ Development

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[all,dev]"              # Install with dev dependencies
pytest                                   # Run tests
make format && make lint                 # Format and lint
```

**[Architecture guide →](docs/architecture/ARCHITECTURE.md) · [Project structure →](docs/architecture/project-structure.md)**

## 🤝 Contributing

We welcome bug reports and feature requests via [GitHub Issues](https://github.com/Traigent/Traigent/issues). For security vulnerabilities, please email security@traigent.ai.

## 📄 License

This project is **dual-licensed**: the GNU Affero General Public License v3.0 only (AGPL-3.0-only) - see [LICENSE](LICENSE) - **or** a Traigent commercial license under a separate written agreement (see [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md)). SPDX: `AGPL-3.0-only OR LicenseRef-Traigent-Commercial`. Commercial inquiries: legal@traigent.ai.

---

**[Get Started →](docs/getting-started/GETTING_STARTED.md)** | **[Examples →](examples/)** | **[Portal →](https://portal.traigent.ai)** | **[Skill →](docs/agent-skill.md)** | **[Walkthrough →](docs/walkthrough.md)** | **[GitHub Issues](https://github.com/Traigent/Traigent/issues)** | **[Discussions](https://github.com/Traigent/Traigent/discussions)**
