chore: init claude.md (#1449)

Author: cosmin-staicu

CLAUDE.md

@@ -0,0 +1,108 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+This is the **UiPath Python SDK** monorepo — a Python SDK and CLI for programmatic interaction with the UiPath Cloud Platform. It publishes three packages to PyPI: `uipath`, `uipath-core`, and `uipath-platform`.
+
+## Monorepo Structure
+
+The repo contains three packages under `packages/`, each with its own `pyproject.toml`, `src/`, and `tests/`:
+
+- **`packages/uipath`** — The main SDK package. Contains the CLI (`uipath` command), agent framework, evaluation framework, tracing/telemetry, and function utilities. This is what users `uv pip install uipath`. Entry point: `src/uipath/_cli:cli`.
+- **`packages/uipath-core`** — Core abstractions shared across packages: tracing, serialization, events, feature flags, error types, chat models, guardrails. Depends on OpenTelemetry and Pydantic.
+- **`packages/uipath-platform`** — HTTP client layer for UiPath Platform APIs. Contains service classes for orchestrator resources (assets, buckets, jobs, processes, queues), action center, context grounding, documents, connections, chat, and guardrails. Depends on `uipath-core`, httpx, and tenacity.
+
+Dependency chain: `uipath` → `uipath-platform` → `uipath-core`. Local editable links are configured via `[tool.uv.sources]`.
+
+## Build & Development Commands
+
+All packages use **uv** for dependency management and **hatch** as the build backend.
+
+```bash
+# Install dependencies (run from each package directory)
+cd packages/uipath && uv sync --all-extras
+
+# The main package has a justfile (run from packages/uipath/):
+just lint        # ruff check + custom httpx linter
+just format      # ruff format --check
+just validate    # lint + format
+just build       # validate + update-agents-md + uv build
+just install     # uv sync --all-extras
+```
+
+### Linting & Formatting
+
+```bash
+# From any package directory:
+ruff check .          # Lint (rules: E, F, B, I, D; Google-style docstrings)
+ruff format --check . # Format check
+ruff check --fix .    # Auto-fix lint issues
+ruff format .         # Auto-format
+
+# Custom linter (packages/uipath only):
+python scripts/lint_httpx_client.py
+```
+
+Ruff config: line-length 88, double quotes, space indent. Docstring rules (D) are disabled for tests. Line length (E501) is ignored globally.
+
+### Type Checking
+
+```bash
+# From any package directory:
+mypy src tests
+```
+
+Uses pydantic mypy plugin. Configured in each package's `pyproject.toml`.
+
+### Running Tests
+
+```bash
+# From any package directory:
+pytest                           # Run all tests
+pytest tests/cli/                # Run a test subdirectory
+pytest tests/cli/test_pack.py    # Run a specific file
+pytest tests/cli/test_pack.py::test_name  # Run a single test
+pytest -x                        # Stop on first failure
+```
+
+All packages use pytest with pytest-asyncio (auto mode), pytest-httpx for HTTP mocking, pytest-cov for coverage. Tests are in `tests/` within each package.
+
+### Pre-commit
+
+The repo has a `.pre-commit-config.yaml` with ruff hooks (check + format).
+
+## Key Architecture Details
+
+### Platform Services Pattern (uipath-platform)
+
+Each orchestrator resource follows a two-file pattern in `packages/uipath-platform/src/uipath/platform/orchestrator/`:
+- `_<resource>_service.py` — Internal service class with HTTP client logic (httpx calls, URL construction, error handling)
+- `<resource>.py` — Public-facing wrapper that delegates to the service class
+
+Service method naming convention:
+- `retrieve` — get a single resource by key
+- `retrieve_by_[field]` — get a resource by an alternate field
+- `list` — get multiple resources
+
+### CLI Architecture (packages/uipath)
+
+The CLI uses **click** and is organized as `cli_<command>.py` files in `src/uipath/_cli/`. Heavy imports are deferred (lazy-loaded) to keep startup fast — do not add top-level imports to `_cli/__init__.py`.
+
+### Agent Framework
+
+`src/uipath/agent/` contains the agent runtime. Agents use Pydantic models for Input/Output schemas.
+
+### Evaluation Framework
+
+`src/uipath/eval/` provides evaluators (ExactMatch, Contains, JsonSimilarity, LLMJudge, Trajectory, ToolCall, Classification) for testing agent quality.
+
+## Code Conventions
+
+- Python 3.11+ required
+- Always add type annotations to functions and classes
+- Use Google-style docstrings for public APIs
+- Use `httpx` for HTTP requests (never `requests`)
+- Use `pydantic` for data models
+- Tests use pytest only (no unittest module); pytest-asyncio auto mode means async tests don't need `@pytest.mark.asyncio`

packages/uipath-core/CLAUDE.md

@@ -0,0 +1,60 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with the `uipath-core` package.
+
+## Package Purpose
+
+Core abstractions shared across the UiPath Python SDK. This is the lowest-level package — it has no dependency on `uipath` or `uipath-platform`. Depends on OpenTelemetry and Pydantic.
+
+## Development Commands
+
+```bash
+cd packages/uipath-core
+
+uv sync --all-extras          # Install dependencies
+pytest                        # Run all tests
+pytest tests/tracing/         # Run a test subdirectory
+pytest tests/tracing/test_traced.py::test_name  # Single test
+ruff check .                  # Lint
+ruff format --check .         # Format check
+mypy src tests                # Type check
+```
+
+No justfile exists for this package — run commands directly.
+
+## Modules
+
+### `chat/` — Conversation Protocol Models
+Pydantic models for a hierarchical conversation event protocol (sessions, exchanges, messages, tool calls, citations, interrupts, content parts, async streams). ~45 exported classes. This defines the wire format between UI clients and agents/LLMs.
+
+### `tracing/` — OpenTelemetry Instrumentation
+- `@traced` decorator — instruments sync/async functions with OpenTelemetry spans. Supports `recording=False` for non-recording spans, custom `input_processor`/`output_processor`, and span context propagation.
+- `UiPathTraceManager` — central management of tracer providers, span processors, and exporters.
+- `UiPathSpanUtils` — span registry and utilities.
+- `UiPathTraceSettings` — settings with optional `span_filter` callable.
+
+### `guardrails/` — Deterministic Validation Rules
+Rule engine for validating input/output data with `WordRule`, `NumberRule`, `BooleanRule`, `UniversalRule`. `DeterministicGuardrailsService` evaluates rules pre- and post-execution (skipping output-dependent rules during pre-execution).
+
+### `serialization/` — JSON Serialization
+`serialize_json()`, `serialize_object()`, `serialize_defaults()` — handles Pydantic v1/v2, dataclasses, enums, datetime, namedtuples, sets.
+
+### `events/` — Event Bus
+`EventBus` — simple async pub/sub with `subscribe()`, `unsubscribe()`, `publish()`.
+
+### `feature_flags/` — Feature Flag Registry
+`FeatureFlags` singleton. Sources: programmatic config (takes precedence) + `UIPATH_FEATURE_*` env vars. Supports structured types via JSON parsing.
+
+### `errors/` — Exception Types
+`UiPathFaultedTriggerError`, `UiPathPendingTriggerError`, `ErrorCategory` enum (DEPLOYMENT, SYSTEM, UNKNOWN, USER).
+
+### `triggers/` — Resume Trigger Models
+`UiPathResumeTrigger`, `UiPathApiTrigger`, and trigger type/name enums. Pydantic models with camelCase aliases.
+
+## Test Structure
+
+Tests mirror the module structure under `tests/`. The `tracing/` subdirectory has the most tests (8 files covering decorator behavior, span nesting, registry, filtering, serialization, external integration).
+
+### Key Test Fixture
+
+`conftest.py` provides a session-scoped `span_capture` fixture using `InMemorySpanExporter`. An autouse fixture `clear_spans_between_tests` resets it before each test. Use `span_capture.get_spans()` to assert on traced function behavior.

packages/uipath-platform/CLAUDE.md

@@ -0,0 +1,119 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with the `uipath-platform` package.
+
+## Package Purpose
+
+HTTP client layer for UiPath Platform APIs. Provides typed service classes for all orchestrator and platform resources. Depends on `uipath-core`, httpx, tenacity, and pydantic.
+
+## Development Commands
+
+```bash
+cd packages/uipath-platform
+
+uv sync --all-extras          # Install dependencies
+pytest                        # Run all tests
+pytest tests/services/test_assets_service.py  # Single test file
+ruff check .                  # Lint
+ruff format --check .         # Format check
+mypy src tests                # Type check
+```
+
+No justfile exists for this package — run commands directly.
+
+## Entry Point: `UiPath` Class
+
+`_uipath.py` defines the main `UiPath` class that exposes all services as properties:
+
+```python
+from uipath.platform import UiPath
+sdk = UiPath()
+sdk.assets              # AssetsService
+sdk.attachments         # AttachmentsService
+sdk.processes           # ProcessesService
+sdk.buckets             # BucketsService
+sdk.queues              # QueuesService
+sdk.jobs                # JobsService
+sdk.folders             # FolderService
+sdk.tasks               # TasksService (Action Center)
+sdk.connections         # ConnectionsService
+sdk.context_grounding   # ContextGroundingService
+sdk.documents           # DocumentsService
+sdk.entities            # EntitiesService
+sdk.llm                 # UiPathLlmChatService
+sdk.llm_openai          # UiPathOpenAIService
+sdk.conversational      # ConversationsService
+sdk.guardrails          # GuardrailsService
+sdk.agenthub            # AgentHubService
+sdk.mcp                 # McpService
+sdk.resource_catalog    # ResourceCatalogService
+sdk.automation_tracker  # AutomationTrackerService
+```
+
+### Authentication
+
+Credentials can be provided via constructor parameters or environment variables (`UIPATH_URL`, `UIPATH_ACCESS_TOKEN`). Two auth modes are supported:
+
+- **User authentication** — provide `base_url` and `secret` (access token), or set them via env vars
+- **S2S (service-to-service)** — provide `client_id` and `client_secret` (both required together), optionally with `scope`; uses `ExternalApplicationService` internally to exchange for an access token
+
+Configuration is validated with Pydantic; missing `base_url` raises `BaseUrlMissingError`, missing `secret` raises `SecretMissingError`.
+
+## Service Architecture
+
+### Two-File Pattern (orchestrator/)
+
+Each orchestrator resource uses two files:
+- **`_<resource>_service.py`** — Internal service class extending `BaseService` and `FolderContext`. Contains HTTP logic (httpx calls, URL construction, retry, error handling). Methods decorated with `@traced` and `@resource_override`.
+- **`<resource>.py`** — Public Pydantic models for the resource.
+
+### BaseService (`common/_base_service.py`)
+
+All services inherit from `BaseService` which provides:
+- `request()` / `request_async()` — HTTP methods with tenacity-based retry (exponential backoff)
+- Automatic exception enrichment via `EnrichedException`
+- User-agent tracking and span utilities
+
+### FolderContext (`common/_folder_context.py`)
+
+Manages folder scoping (by `folder_key` or `folder_path`) for orchestrator operations.
+
+### Method Naming Convention
+
+- `retrieve` — get single resource by key
+- `retrieve_by_[field]` — get by alternate field
+- `list` — get multiple resources
+
+### Sync + Async
+
+Services provide both sync and async variants (e.g., `.invoke()` and `.invoke_async()`).
+
+## Modules Beyond Orchestrator
+
+| Module | Purpose |
+|--------|---------|
+| `action_center/` | Task management for human-in-the-loop workflows |
+| `agenthub/` | System agents and LLM model discovery |
+| `automation_tracker/` | Business Transaction Service (BTS) for Process Mining |
+| `chat/` | LLM gateway, conversations, throttling |
+| `connections/` | External connection management |
+| `context_grounding/` | RAG services (DeepRAG, batch RAG, ephemeral indexes) |
+| `documents/` | Document Understanding (IXP) |
+| `entities/` | Data Service entity management |
+| `guardrails/` | LLM output guardrails |
+| `resource_catalog/` | Resource discovery and metadata |
+| `resume_triggers/` | HITL trigger creation/reading protocols |
+| `common/` | Shared base classes, config, auth, retry, paging, validation |
+| `errors/` | Custom exceptions (`EnrichedException`, `FolderNotFoundException`, `BaseUrlMissingError`, etc.) |
+
+## Test Structure
+
+All tests are under `tests/services/` with one test file per service. Tests use `pytest-httpx` for HTTP mocking.
+
+### Key Test Fixtures (`tests/services/conftest.py`)
+
+- `base_url` — returns `"https://test.uipath.com"`
+- `config` — `UiPathApiConfig` instance
+- `execution_context` — `UiPathExecutionContext` with mocked `UIPATH_ROBOT_KEY`
+- `mock_env_vars` — standard mock env vars (URL, tokens, IDs)
+- Service-specific fixtures (e.g., `jobs_service`) built from config + execution_context