Skip to content

CLAUDE.md

Latest commit

 

History

History
82 lines (50 loc) · 4.04 KB

CLAUDE.md

File metadata and controls

82 lines (50 loc) · 4.04 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

uipath-langchain is a Python SDK that extends UiPath's Python SDK with LangChain/LangGraph integration. It implements the UiPath Runtime Protocol to deploy LangGraph agents to UiPath Cloud Platform. Requires Python 3.11+.

Common Commands

# Install dependencies (uses uv)
uv sync --all-extras

# Run all tests
uv run pytest

# Run a single test file
uv run pytest tests/path/to/test_file.py

# Run a single test
uv run pytest tests/path/to/test_file.py::test_name

# Lint
just lint              # ruff check + httpx client lint
just format            # ruff format check + fix

# Build
uv build

Architecture

Package: src/uipath_langchain/

  • runtime/ — UiPathLangGraphRuntime executes LangGraph graphs within the UiPath framework. Async execution with streaming, breakpoints, and message mapping. Registered as an entry point via uipath_langchain.runtime:register_runtime_factory.

  • agent/ — Agent implementation with sub-packages:

    • react/ — ReAct agent pattern (agent, LLM node, router, tool node, guardrails)
    • tools/ — Structured tools: context, escalation, extraction, integration, process, MCP adapters, durable interrupts. All inherit from BaseUiPathStructuredTool.
    • guardrails/ — Input/output validation within agent execution
    • multimodal/ — Multimodal invoke support
    • exceptions/ — Structured error types (AgentRuntimeError, AgentStartupError) and helpers for agent error handling
    • wrappers/ — Agent decorators and wrappers

  • chat/ — LLM provider interfaces for OpenAI, Azure OpenAI, AWS Bedrock, Google Vertex AI. Uses lazy imports via __getattr__ in __init__.py to keep CLI startup fast. Includes hitl.py with the requires_approval decorator for human-in-the-loop workflows. Factory pattern via chat_model_factory.py.

  • retrievers/ and vectorstores/ — Context grounding retrieval and vector storage.

  • guardrails/ — Top-level guardrails with actions, enums, models, and middleware.

  • _cli/ — CLI commands (uipath init, uipath new) with project templates.

  • _tracing/ — OpenTelemetry instrumentation.

  • _utils/ — Shared utilities: HTTP request mixin, settings, sleep policy, environment helpers.

  • middlewares.py — Entry point registered as uipath_langchain.middlewares:register_middleware.

Entry Points (pyproject.toml)

The package registers two entry points consumed by the uipath CLI:

  • uipath.middleware → uipath_langchain.middlewares:register_middleware
  • uipath.runtime_factory → uipath_langchain.runtime:register_runtime_factory

Key Conventions

  • httpx clients: Always use **get_httpx_client_kwargs() when constructing httpx.Client() or httpx.AsyncClient(). A custom AST linter (scripts/lint_httpx_client.py) enforces this — it runs as part of just lint.

  • Lazy imports: The chat/ module defers heavy imports (langchain_openai, openai SDK) to optimize CLI startup. Use __getattr__ pattern in __init__.py when adding new chat model providers.

  • Naming conventions for SDK methods: retrieve (single by key), retrieve_by_[field] (single by other field), list (multiple resources).

  • Testing: pytest only (no unittest). Tests in ./tests/ mirror source structure. Use pytest-asyncio for async tests (mode: auto). A circular import test (test_no_circular_imports.py) auto-discovers and validates all modules.

  • Type annotations: All functions and classes require type annotations. Public APIs require Google-style docstrings.

  • Linting: Ruff with rules E, F, B, I. Line length 88. mypy with pydantic plugin for type checking.

  • Bedrock/Vertex imports: bedrock.py and vertex.py have per-file E402 ignores for conditional imports.

  • Exception handling in agent/: Use the error types and helpers from agent/exceptions/. Do not raise raw exceptions or invent new error types. New error codes may be defined.