Skip to content

Commit 1fbdb2f

Browse files
gheorghitahurmuzgheorghitahurmuz
committed
chore: remove outdated cursor rules and add AGENTS.md for project guidance
1 parent e521603 commit 1fbdb2f

File tree

3 files changed

+283
-55
lines changed

3 files changed

+283
-55
lines changed

‎.cursorrules‎

Lines changed: 0 additions & 55 deletions
This file was deleted.

‎AGENTS.md‎

Lines changed: 282 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
1+
# AGENTS.md
2+
3+
This file provides guidance to AI agents when working with code in this repository.
4+
5+
## Project Overview
6+
7+
UiPath Python SDK and CLI for programmatic interaction with UiPath Cloud Platform services. The package provides both:
8+
- **SDK**: Python API for services (processes, assets, buckets, jobs, context grounding, etc.)
9+
- **CLI**: Command-line tool for creating, packaging, debugging, and deploying automation projects to UiPath Cloud Platform
10+
11+
## Development Commands
12+
13+
### Environment Setup
14+
```bash
15+
# Create virtual environment
16+
uv venv
17+
18+
# Activate virtual environment
19+
source .venv/bin/activate # Linux/Mac
20+
# or
21+
.venv\Scripts\Activate.ps1 # Windows PowerShell
22+
23+
# Install dependencies
24+
uv sync --all-extras --no-cache
25+
```
26+
27+
### Build & Quality Checks
28+
```bash
29+
# Lint code (includes custom httpx client linting)
30+
just lint
31+
# or: ruff check .
32+
33+
# Format code
34+
just format
35+
# or: ruff format --check .
36+
37+
# Run both lint and format
38+
just validate
39+
40+
# Build package (includes validation and agent markdown updates)
41+
just build
42+
# or: uv build
43+
44+
# Run pre-commit hooks manually
45+
pre-commit run --all-files
46+
```
47+
48+
### Testing
49+
```bash
50+
# Run all tests with coverage
51+
pytest
52+
53+
# Run specific test file
54+
pytest tests/sdk/services/test_assets_service.py
55+
56+
# Run specific test function
57+
pytest tests/sdk/services/test_assets_service.py::test_retrieve_asset
58+
59+
# Run tests in specific directory
60+
pytest tests/sdk/
61+
62+
# Run with verbose output
63+
pytest -v
64+
65+
# Run async tests (uses pytest-asyncio)
66+
pytest tests/sdk/services/test_async_operations.py
67+
```
68+
69+
### CLI Development
70+
```bash
71+
# Test CLI commands locally (must be in venv)
72+
uipath --help
73+
uipath auth
74+
uipath init
75+
uipath pack
76+
uipath publish
77+
78+
# Install SDK in editable mode for local development
79+
uv add --editable /path/to/uipath-python
80+
```
81+
82+
## Architecture
83+
84+
### Core Components
85+
86+
**SDK Entry Point (`src/uipath/_uipath.py`)**
87+
- `UiPath` class: Main SDK interface providing property-based access to all services
88+
- Services instantiated lazily via `@property` methods
89+
- Shared `Config` and `ExecutionContext` passed to all services
90+
91+
**Configuration (`src/uipath/_config.py`)**
92+
- `Config`: Holds `base_url` and `secret` for authentication
93+
- Credentials resolved from: constructor args → env vars (UIPATH_URL, UIPATH_ACCESS_TOKEN) → .env file
94+
95+
**Execution Context (`src/uipath/_execution_context.py`)**
96+
- Manages runtime environment info: job instance ID, job key, robot key
97+
- Reads from environment variables set by UiPath Robot during execution
98+
- Used for job tracking and telemetry
99+
100+
**Folder Context (`src/uipath/_folder_context.py`)**
101+
- Manages folder scope for UiPath resources (processes, assets, etc.)
102+
- Provides `folder_headers` for API requests based on UIPATH_FOLDER_KEY or UIPATH_FOLDER_PATH
103+
- Inherited by services that need folder-scoped operations
104+
105+
**Base Service (`src/uipath/_services/_base_service.py`)**
106+
- All services extend `BaseService`
107+
- Provides both sync (`httpx.Client`) and async (`httpx.AsyncClient`) HTTP clients
108+
- Automatic retry logic for 5xx errors and connection timeouts using tenacity
109+
- Standard headers (authorization, user-agent) applied to all requests
110+
- Request overrides manager for testing/mocking
111+
112+
### Services Architecture (`src/uipath/_services/`)
113+
114+
Each service follows this pattern:
115+
1. Extends `BaseService` (some also extend `FolderContext` for folder-scoped operations)
116+
2. Constructor: `__init__(self, config: Config, execution_context: ExecutionContext, ...)`
117+
3. Methods use standard naming:
118+
- `retrieve(key)` - Get single resource by primary identifier
119+
- `retrieve_by_[field](value)` - Get resource by alternate field
120+
- `list(filters)` - Get multiple resources
121+
- `create(data)` - Create new resource
122+
- `update(key, data)` - Modify existing resource
123+
- `delete(key)` - Remove resource
124+
125+
**Key Services:**
126+
- `ApiClient`: Direct HTTP access for custom requests
127+
- `ProcessesService`: Execute and manage automation processes
128+
- `AssetsService`: Access shared variables/credentials
129+
- `JobsService`: Monitor job execution
130+
- `BucketsService`: Cloud storage operations
131+
- `ContextGroundingService`: AI-enabled semantic search and knowledge grounding
132+
- `ConnectionsService`: External system integrations
133+
- `QueuesService`: Transaction queue management
134+
- `ActionsService`: Action Center task management
135+
136+
### CLI Architecture (`src/uipath/_cli/`)
137+
138+
**Entry Point (`__init__.py`)**
139+
- Click-based CLI with multiple commands
140+
- Commands: `new`, `init`, `pack`, `publish`, `run`, `deploy`, `auth`, `invoke`, `push`, `pull`, `eval`, `dev`, `debug`
141+
- Loads `.env` automatically and adds CWD to Python path
142+
143+
**Key CLI Modules:**
144+
- `cli_auth.py`: OAuth authentication flow, creates/updates .env file
145+
- `cli_init.py`: Creates uipath.json config for project
146+
- `cli_pack.py`: Packages project into .nupkg for UiPath deployment
147+
- `cli_publish.py`: Uploads package to Orchestrator
148+
- `cli_run.py`: Local execution with input args
149+
- `cli_debug.py`: Debug mode execution
150+
- `_templates/`: Project scaffolding templates
151+
- `_push/`: Package deployment logic
152+
- `_evals/`: Evaluation framework for agent testing
153+
154+
### Agent Framework (`src/uipath/agent/`)
155+
156+
Supports building AI agents for UiPath platform:
157+
- `conversation/`: Conversational agent patterns
158+
- `react/`: ReAct (Reasoning + Acting) agent implementation
159+
- `models/`: Agent definition schemas and data models
160+
161+
### Telemetry & Tracing (`src/uipath/tracing/`, `src/uipath/telemetry/`)
162+
163+
- OpenTelemetry integration for distributed tracing
164+
- Azure Monitor exporters for cloud telemetry
165+
- `@traced` decorator for automatic span creation
166+
167+
### Utilities (`src/uipath/_utils/`)
168+
169+
- `_auth.py`: Credential resolution (OAuth, PAT tokens)
170+
- `_url.py`: URL parsing and validation for UiPath endpoints
171+
- `_logs.py`: Structured logging setup
172+
- `_endpoint.py`: API endpoint construction
173+
- `_infer_bindings.py`: Type inference for agent bindings
174+
- `_request_spec.py`: Request specification helpers
175+
- `_ssl_context.py`: SSL/TLS configuration for httpx
176+
177+
## Coding Standards
178+
179+
### Type Annotations
180+
- **Required** on all functions and classes (public and internal)
181+
- Include return types explicitly
182+
- Use `Optional[T]` for nullable values
183+
- Use `Union[A, B]` for multiple types (or `A | B` for Python 3.10+)
184+
185+
### Docstrings
186+
- **Required** for all public functions and classes
187+
- Use **Google-style convention**
188+
- Reference https://docs.uipath.com for UiPath concepts
189+
- Example:
190+
```python
191+
def retrieve(self, name: str) -> Asset:
192+
"""Retrieve an asset by name.
193+
194+
Args:
195+
name: The name of the asset to retrieve.
196+
197+
Returns:
198+
The asset object.
199+
200+
Raises:
201+
AssetNotFoundError: If the asset does not exist.
202+
"""
203+
```
204+
205+
### Service Method Naming
206+
- `retrieve` not `retrieve_user` (method is already scoped to service)
207+
- `retrieve_by_email` for alternate lookups
208+
- `list` not `list_users`
209+
- This applies to core SDK methods only, not internal utilities
210+
211+
### Testing
212+
- Use **pytest only** (no unittest module)
213+
- All tests in `./tests` directory mirroring `./src/uipath` structure
214+
- Tests require type annotations and docstrings
215+
- Import pytest types when TYPE_CHECKING:
216+
```python
217+
from typing import TYPE_CHECKING
218+
219+
if TYPE_CHECKING:
220+
from _pytest.capture import CaptureFixture
221+
from _pytest.fixtures import FixtureRequest
222+
from _pytest.logging import LogCaptureFixture
223+
from _pytest.monkeypatch import MonkeyPatch
224+
from pytest_mock.plugin import MockerFixture
225+
```
226+
- Use pytest plugins: pytest-asyncio, pytest-httpx, pytest-cov, pytest-mock
227+
- Create `__init__.py` files in test directories as needed
228+
229+
### Code Style
230+
- Line length: 88 characters (Ruff default)
231+
- 4-space indentation
232+
- Double quotes for strings
233+
- Ruff linting rules: E (errors), F (pyflakes), B (bugbear), I (isort), D (pydocstyle)
234+
- Google-style docstrings enforced via ruff (convention = "google")
235+
- Tests and docs exempt from docstring requirements
236+
237+
### Error Handling
238+
- Robust error handling with context capture
239+
- Custom exceptions in `src/uipath/models/errors.py` and `exceptions.py`
240+
- Use `EnrichedException` for enhanced error details
241+
242+
### File Organization
243+
- Source: `src/uipath/`
244+
- Tests: `tests/` (mirror source structure)
245+
- Docs: `docs/`
246+
- Scripts: `scripts/` (build utilities, linters)
247+
- Samples: `samples/` (excluded from linting)
248+
- Test cases: `testcases/` (excluded from linting)
249+
250+
## Important Notes
251+
252+
### Custom Linters
253+
- Custom linter enforces httpx client usage patterns: `scripts/lint_httpx_client.py`
254+
- Run via `just lint` or `python scripts/lint_httpx_client.py`
255+
256+
### Package Building
257+
- `pyproject.toml` must include description (avoid: &, <, >, ", ', ;) and author info
258+
- Build process updates agent markdown: `scripts/update_agents_md.py`
259+
- Uses Hatchling build backend
260+
261+
### Dependencies
262+
- **uv**: Fast Python package manager (replaces pip/poetry)
263+
- **httpx**: Async HTTP client (not requests)
264+
- **pydantic**: Data validation and settings
265+
- **click**: CLI framework
266+
- **tenacity**: Retry logic
267+
- **python-dotenv**: .env file support
268+
- **OpenTelemetry**: Distributed tracing
269+
270+
### Pre-commit Hooks
271+
- Ruff format and lint run automatically on commit
272+
- Configure via `.pre-commit-config.yaml`
273+
274+
### Environment Variables
275+
SDK requires:
276+
- `UIPATH_URL`: Full URL to tenant (e.g., https://cloud.uipath.com/org/tenant)
277+
- `UIPATH_ACCESS_TOKEN`: Personal access token or OAuth token
278+
279+
Optional (set by UiPath Robot):
280+
- `UIPATH_JOB_ID`, `UIPATH_JOB_KEY`: Job tracking
281+
- `UIPATH_ROBOT_KEY`: Robot identification
282+
- `UIPATH_FOLDER_KEY` or `UIPATH_FOLDER_PATH`: Folder scope

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@AGENTS.md

0 commit comments

Comments
 (0)