From 0e63d3f9d0e89db20cb72d47b009ea1f65e845ed Mon Sep 17 00:00:00 2001
From: giuliastf <giuliaimbrea02@gmail.com>
Date: Mon, 25 May 2026 16:39:54 +0300
Subject: [PATCH] docs(add-setup-md): add SETUP.md for Agentic Inner Loop KPI

---
 SETUP.MD | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 SETUP.MD

diff --git a/SETUP.MD b/SETUP.MD
new file mode 100644
index 000000000..5248054b9
--- /dev/null
+++ b/SETUP.MD
@@ -0,0 +1,109 @@
+# SETUP.md
+
+## Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) 0.5+
+
+### Supported platforms
+
+This checklist controls the Agentic Inner Loop KPI pipeline targets (clean Linux VM). The repo's own GitHub Actions CI additionally tests on `windows-latest`, but that is not measured by this KPI.
+
+- [x] Linux
+- [ ] Windows
+- [ ] macOS
+
+## Environment Variables
+
+### Standard (injected by pipeline)
+
+None of the standard pipeline variables are required for environment setup, build, or unit tests.
+
+### Project-specific
+
+None. The unit-test suites under the `Test` section below run fully offline and require no external authentication. The repo's optional E2E tests (`pytest -m e2e`) are excluded from this KPI; their credentials (`UIPATH_URL`, `UIPATH_CLIENT_ID`, `UIPATH_CLIENT_SECRET`, `UIPATH_FOLDER_KEY`) are wired only in the dedicated GitHub Actions `e2e-uipath-platform` job and are out of scope here.
+
+## Setup
+
+```bash
+# Install uv if not present
+curl -LsSf https://astral.sh/uv/install.sh | sh
+export PATH="$HOME/.local/bin:$PATH"
+
+# Sync all three packages with dev dependencies (dependency order: core → platform → main)
+uv --directory packages/uipath-core sync --all-extras
+uv --directory packages/uipath-platform sync --all-extras
+uv --directory packages/uipath sync --all-extras
+```
+
+## Verify Setup
+
+```bash
+python3 --version
+uv --version
+uv --directory packages/uipath-core run python -c "import uipath.core; print('uipath-core ok')"
+uv --directory packages/uipath-platform run python -c "import uipath.platform; print('uipath-platform ok')"
+uv --directory packages/uipath run python -c "import uipath; print('uipath ok')"
+```
+
+## Build
+
+```bash
+uv --directory packages/uipath-core build
+uv --directory packages/uipath-platform build
+uv --directory packages/uipath build
+```
+
+## Test
+
+```bash
+uv --directory packages/uipath-core run pytest -m "not e2e"
+uv --directory packages/uipath-platform run pytest -m "not e2e"
+uv --directory packages/uipath run pytest -m "not e2e"
+```
+
+## Sample Code Change
+
+### The change
+
+Add a new `size` property to `SpanRegistry` in `packages/uipath-core/src/uipath/core/tracing/span_utils.py`, immediately after the `clear` method (around line 130) and before the `# Global span registry instance` comment:
+
+```python
+@property
+def size(self) -> int:
+    """Return the number of currently registered spans."""
+    return len(self._spans)
+```
+
+Then create `packages/uipath-core/tests/tracing/test_span_registry_size.py` with two pytest tests:
+
+```python
+from unittest.mock import MagicMock
+
+from uipath.core.tracing.span_utils import SpanRegistry
+
+
+def _make_span(span_id: int) -> MagicMock:
+    span = MagicMock()
+    span.get_span_context.return_value.span_id = span_id
+    span.parent = None  # registered as a root span (no parent)
+    return span
+
+
+def test_size_empty_registry() -> None:
+    registry = SpanRegistry()
+    assert registry.size == 0
+
+
+def test_size_after_registrations() -> None:
+    registry = SpanRegistry()
+    registry.register_span(_make_span(1))
+    registry.register_span(_make_span(2))
+    assert registry.size == 2
+```
+
+### Verification
+
+```bash
+uv --directory packages/uipath-core run pytest tests/tracing/test_span_registry_size.py -v
+```