From 0782160f2ce7a8e20e606de406dd5f01cdd40400 Mon Sep 17 00:00:00 2001 From: Rishav C Date: Wed, 10 Sep 2025 16:01:08 -0400 Subject: [PATCH] Add Claude Code and Cursor IDE configuration - Add Claude Code settings with permissions for web search, docs access, and rye commands - Add comprehensive Cursor rules for repository tooling, architecture, and development workflow - Add CLAUDE.md with detailed development commands and architecture overview - Update CONTRIBUTING.md with vibe coding setup instructions for both Claude Code and Cursor --- .claude/settings.json | 15 ++++ .cursor/rules/00_repo_tooling.mdc | 24 ++++++ .cursor/rules/05_permissions_and_tools.mdc | 18 +++++ .cursor/rules/10_architecture.mdc | 30 +++++++ .cursor/rules/20_codegen_boundaries.mdc | 11 +++ .cursor/rules/30_cli_and_commands.mdc | 18 +++++ .cursor/rules/40_temporal_and_agents.mdc | 17 ++++ .cursor/rules/50_tests_and_mocking.mdc | 16 ++++ .cursor/rules/60_style_lint_typecheck.mdc | 16 ++++ .cursor/rules/70_examples_and_docs.mdc | 11 +++ CLAUDE.md | 93 ++++++++++++++++++++++ CONTRIBUTING.md | 30 +++++++ 12 files changed, 299 insertions(+) create mode 100644 .claude/settings.json create mode 100644 .cursor/rules/00_repo_tooling.mdc create mode 100644 .cursor/rules/05_permissions_and_tools.mdc create mode 100644 .cursor/rules/10_architecture.mdc create mode 100644 .cursor/rules/20_codegen_boundaries.mdc create mode 100644 .cursor/rules/30_cli_and_commands.mdc create mode 100644 .cursor/rules/40_temporal_and_agents.mdc create mode 100644 .cursor/rules/50_tests_and_mocking.mdc create mode 100644 .cursor/rules/60_style_lint_typecheck.mdc create mode 100644 .cursor/rules/70_examples_and_docs.mdc create mode 100644 CLAUDE.md diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000..378d0ebe --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,15 @@ +{ + "permissions": { + "allow": [ + "WebSearch", + "WebFetch(domain:docs.temporal.io)", + "Bash(rye run pytest:*)", + "Bash(rye run lint:*)", + "Bash(rye run typecheck:*)", + "Bash(rye run sync:*)", + "Bash(rye run build:*)" + ], + "deny": [], + "ask": [] + } +} \ No newline at end of file diff --git a/.cursor/rules/00_repo_tooling.mdc b/.cursor/rules/00_repo_tooling.mdc new file mode 100644 index 00000000..ca3a44cb --- /dev/null +++ b/.cursor/rules/00_repo_tooling.mdc @@ -0,0 +1,24 @@ +--- +description: Project-wide tooling, env, and command conventions +globs: "**/*" +alwaysApply: true +--- + +Use Rye for Python dependency management and workflows. Prefer these commands: + +- Setup env: `./scripts/bootstrap` or `rye sync --all-features` [[Use Rye in this repo]] +- Run tests: `rye run pytest` or `./scripts/test` +- Run a specific test: `rye run pytest path/to/test_file.py::TestClass::test_method -v` +- Format: `rye run format` or `./scripts/format` +- Lint: `rye run lint` or `./scripts/lint` +- Type check: `rye run typecheck` (runs pyright and mypy) +- Build: `rye build` + +Environment requirements: + +- Python 3.12+ is required +- A mock server auto-starts for tests on port 4010 + +Notes: + +- Only use `uv` inside of tutorial folders which have their own virtualenv (managed by a tutorial specific pyproject.toml inside the relevant tutorial folder). Otherwise use rye at the top level. diff --git a/.cursor/rules/05_permissions_and_tools.mdc b/.cursor/rules/05_permissions_and_tools.mdc new file mode 100644 index 00000000..72ff6597 --- /dev/null +++ b/.cursor/rules/05_permissions_and_tools.mdc @@ -0,0 +1,18 @@ +--- +description: Cursor agent permissions and allowed tools aligned with Claude settings +globs: "**/*" +alwaysApply: true +--- + +When invoking external tools or the terminal, follow these constraints: + +- Web search is allowed when needed for docs and references +- Prefer fetching docs from `docs.temporal.io` when researching Temporal topics +- Allowed bash commands should go through Rye workflows: + - `rye run pytest:*` + - `rye run lint:*` + - `rye run typecheck:*` + - `rye run sync:*` + - `rye run build:*` + +Default to Rye; only use other tools when explicitly required by the codebase. diff --git a/.cursor/rules/10_architecture.mdc b/.cursor/rules/10_architecture.mdc new file mode 100644 index 00000000..230f1456 --- /dev/null +++ b/.cursor/rules/10_architecture.mdc @@ -0,0 +1,30 @@ +--- +description: Repository architecture overview and code navigation hints +globs: "src/agentex/**, examples/**, tests/**, README.md" +alwaysApply: false +--- + +Code structure expectations: + +- `src/agentex/` contains the core SDK and generated API client code +- `src/agentex/lib/` contains manually maintained code that should not be overwritten by the code generator + - `cli/` Typer-based CLI implementation + - `core/` Core services, adapters, and Temporal workflows + - `sdk/` SDK utilities and FastACP implementation + - `types/` Custom type definitions + - `utils/` Utility functions +- `examples/` provides example implementations and tutorials +- `tests/` contains the test suites + +Key components quick reference: + +- Client Layer: HTTP client for AgentEx API in `_client.py` and `resources/` +- CLI Layer: Typer-based commands under `lib/cli/` +- Core Services: Temporal workflows and services under `lib/core/` +- FastACP: Protocol implementation in `lib/sdk/fastacp/` +- State Machine: Workflow state management in `lib/sdk/state_machine/` + +Generated vs manual code: + +- Treat `src/agentex/lib/**` as manual code; avoid edits in generated areas unless regenerating consistently +- Expect merge conflicts between generator outputs and manual patches; keep custom logic in `lib/` diff --git a/.cursor/rules/20_codegen_boundaries.mdc b/.cursor/rules/20_codegen_boundaries.mdc new file mode 100644 index 00000000..0bd03880 --- /dev/null +++ b/.cursor/rules/20_codegen_boundaries.mdc @@ -0,0 +1,11 @@ +--- +description: Keep manual code separate from generated SDK code +globs: "src/agentex/**" +alwaysApply: true +--- + +Guideline: + +- Avoid modifying auto-generated files in `src/agentex/` except where explicitly intended. Place custom logic, extensions, and higher-level abstractions in `src/agentex/lib/`. +- When adding features, prefer adding new modules under `src/agentex/lib/**` rather than changing generated files directly. +- If a change to generated code is required, document the reason and ensure the generator configuration or upstream schema is updated to make the change reproducible. diff --git a/.cursor/rules/30_cli_and_commands.mdc b/.cursor/rules/30_cli_and_commands.mdc new file mode 100644 index 00000000..f3944234 --- /dev/null +++ b/.cursor/rules/30_cli_and_commands.mdc @@ -0,0 +1,18 @@ +--- +description: Guidance for working with the agentex CLI and commands +globs: "src/agentex/lib/cli/**, src/agentex/lib/core/**" +alwaysApply: false +--- + +The `agentex` CLI exposes: + +- `agentex agents` for get/list/run/build/deploy agents +- `agentex tasks` for get/list/delete tasks +- `agentex secrets` for sync/get/list/delete secrets +- `agentex uv` as a UV wrapper with AgentEx-specific enhancements +- `agentex init` to initialize new agent projects + +Development tips: + +- For agent development, use `agentex agents run --manifest manifest.yaml` +- For debugging, append `--debug-worker` and optionally `--debug-port 5679` diff --git a/.cursor/rules/40_temporal_and_agents.mdc b/.cursor/rules/40_temporal_and_agents.mdc new file mode 100644 index 00000000..43bf2cf8 --- /dev/null +++ b/.cursor/rules/40_temporal_and_agents.mdc @@ -0,0 +1,17 @@ +--- +description: Temporal workflows, activities, and agent development guidance +globs: "src/agentex/lib/core/temporal/**, examples/**/10_temporal/**" +alwaysApply: false +--- + +Temporal integration: + +- Workflow definitions live in `lib/core/temporal/` +- Include activity definitions for different providers and worker implementations +- Keep workflow logic deterministic and side-effect free; move I/O into activities + +Agent framework: + +- Agents are manifest-driven and support multiple agent types (sync and Temporal-based) +- Use the examples under `examples/10_agentic/` and `examples/10_temporal/` for patterns +- For debugging agents, use the CLI flags `--debug-worker` and `--debug-port` diff --git a/.cursor/rules/50_tests_and_mocking.mdc b/.cursor/rules/50_tests_and_mocking.mdc new file mode 100644 index 00000000..420de4ac --- /dev/null +++ b/.cursor/rules/50_tests_and_mocking.mdc @@ -0,0 +1,16 @@ +--- +description: Testing workflow and mock server details +globs: "tests/**, scripts/test, scripts/mock" +alwaysApply: true +--- + +Testing: + +- Run tests with `rye run pytest` or `./scripts/test` +- To run a specific test: `rye run pytest path/to/test_file.py::TestClass::test_method -v` +- A mock server is automatically started for tests on port 4010 + +When writing tests: + +- Prefer deterministic unit tests that do not depend on external services +- Use the mock server and fixtures provided in the repository diff --git a/.cursor/rules/60_style_lint_typecheck.mdc b/.cursor/rules/60_style_lint_typecheck.mdc new file mode 100644 index 00000000..f36f02d7 --- /dev/null +++ b/.cursor/rules/60_style_lint_typecheck.mdc @@ -0,0 +1,16 @@ +--- +description: Formatting, linting, and type checking standards +globs: "src/**, tests/**" +alwaysApply: true +--- + +Standards: + +- Format code via `rye run format` or `./scripts/format` +- Lint via `rye run lint` or `./scripts/lint` +- Type check via `rye run typecheck` (pyright + mypy) + +Guidance: + +- Keep code readable and consistent; prefer small, focused functions +- Avoid introducing style or type violations; fix before committing diff --git a/.cursor/rules/70_examples_and_docs.mdc b/.cursor/rules/70_examples_and_docs.mdc new file mode 100644 index 00000000..7d16e9d0 --- /dev/null +++ b/.cursor/rules/70_examples_and_docs.mdc @@ -0,0 +1,11 @@ +--- +description: How to use examples and documentation for development +globs: "examples/**, README.md" +alwaysApply: false +--- + +Use the `examples/` directory as reference implementations and tutorials. When creating new features: + +- Mirror patterns from the closest matching example +- Keep examples runnable with the documented commands +- Prefer adding or updating examples alongside significant feature changes diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..ffb1e50f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,93 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Development Commands + +### Package Management in the top level repo +- Use `rye` for dependency management (preferred) +- Run `./scripts/bootstrap` to set up the environment +- Or use `rye sync --all-features` directly + +Special note: the individual tutorials maintain their own tutorial specific virtualenv using `uv`. So when testing/running tutorials, you `uv run` instead of `rye run`. Everything else is similar. + +#### Testing +- Run tests: `rye run pytest` or `./scripts/test` +- Run specific test: `rye run pytest path/to/test_file.py::TestClass::test_method -v` +- Mock server is automatically started for tests, runs on port 4010 + +#### Linting and Formatting +- Format code: `rye run format` or `./scripts/format` + * The repository is still in flux, so running format might accidentally change files that aren't part of your scope of changes. So always run `run rye format` with additional arguments to constrain the formatting to the files that you are modifying. +- Lint code: `rye run lint` or `./scripts/lint` +- Type check: `rye run typecheck` (runs both pyright and mypy) + +### Building and Running +- Build package: `rye build` + + + +### CLI Commands +The package provides the `agentex` CLI with these main commands: +- `agentex agents` - Get, list, run, build, and deploy agents +- `agentex tasks` - Get, list, and delete tasks +- `agentex secrets` - Sync, get, list, and delete secrets +- `agentex uv` - UV wrapper with AgentEx-specific enhancements +- `agentex init` - Initialize new agent projects + +### Agent Development +- Run agents: `agentex agents run --manifest manifest.yaml` +- Debug agents: `agentex agents run --manifest manifest.yaml --debug-worker` +- Debug with custom port: `agentex agents run --manifest manifest.yaml --debug-worker --debug-port 5679` + +## Architecture Overview + +### Code Structure +- `/src/agentex/` - Core SDK and generated API client code +- `/src/agentex/lib/` - Custom library code (not modified by code generator) + - `/cli/` - Command-line interface implementation + - `/core/` - Core services, adapters, and temporal workflows + - `/sdk/` - SDK utilities and FastACP implementation + - `/types/` - Custom type definitions + - `/utils/` - Utility functions +- `/examples/` - Example implementations and tutorials +- `/tests/` - Test suites + +### Key Components + +**SDK Architecture:** +- **Client Layer**: HTTP client for AgentEx API (`_client.py`, `resources/`) +- **CLI Layer**: Typer-based command interface (`lib/cli/`) +- **Core Services**: Temporal workflows, adapters, and services (`lib/core/`) +- **FastACP**: Fast Agent Communication Protocol implementation (`lib/sdk/fastacp/`) +- **State Machine**: Workflow state management (`lib/sdk/state_machine/`) + +**Temporal Integration:** +- Workflow definitions in `lib/core/temporal/` +- Activity definitions for different providers +- Worker implementations for running temporal workflows + +**Agent Framework:** +- Manifest-driven agent configuration +- Support for multiple agent types (sync, temporal-based) +- Debugging support with VS Code integration + +### Code Generation +Most SDK code is auto-generated. Manual changes are preserved in: +- `src/agentex/lib/` directory +- `examples/` directory +- Merge conflicts may occur between manual patches and generator changes + +### Key Dependencies +- `temporalio` - Temporal workflow engine +- `typer` - CLI framework +- `pydantic` - Data validation +- `httpx` - HTTP client +- `fastapi` - Web framework +- `ruff` - Linting and formatting +- `pytest` - Testing framework + +### Environment Requirements +- Python 3.12+ required +- Uses Rye for dependency management +- Supports both sync and async client patterns \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 305c811e..04c64123 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -126,3 +126,33 @@ You can release to package managers by using [the `Publish PyPI` GitHub action]( If you need to manually release a package, you can run the `bin/publish-pypi` script with a `PYPI_TOKEN` set on the environment. + +## 🤖 **Vibe Coding Setup** + +This repository is setup with some pre-canned prompts for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) as well as [Cursor](https://cursor.com/). + +### Cursor + +Access to Cursor can be acquired by asking for it in #it-help. Then just loading this repo in the Cursor IDE should enable the prompts. + +### Claude Code + +### 1. Install Claude Code +```bash +npm install -g @anthropic-ai/claude-code +``` + +### 2. Request a LiteLLM API Key +Visit the [LiteLLM User Guide](https://scale.atlassian.net/wiki/spaces/EPD/pages/1490354189/LiteLLM+User+Guide#Requesting-LiteLLM-Key-for-Generic-Usage) to request your API key. + +### 3. Set Environment Variables +```bash +export ANTHROPIC_AUTH_TOKEN=${LITELLM_PROXY_API_KEY} +export ANTHROPIC_BASE_URL="https://litellm.ml-serving-internal.scale.com" +``` + +### 4. Start Claude Code +```bash +claude +``` +This should be run from inside the main repo directory. If you run the command from a terminal inside VSCode, then Claude will use the VSCode editor to show diffs etc. \ No newline at end of file