diff --git a/.claude/rules/development-workflow.md b/.claude/rules/development-workflow.md new file mode 100644 index 0000000..c4ea3dc --- /dev/null +++ b/.claude/rules/development-workflow.md @@ -0,0 +1,63 @@ +--- +description: Code style, file naming, and project conventions. (project) +alwaysApply: true +--- + +# Development Workflow + +This rule provides code style guidelines and project conventions for the StackOne AI Python SDK. + +## Code Style + +- Use [ruff](https://docs.astral.sh/ruff/) for linting and formatting +- Follow PEP 8 style guidelines +- Maximum line length: 88 characters (ruff default) +- Run `just lint` to check, `just lint-fix` to auto-fix + +## Type Annotations + +- Full type annotations required for all public APIs +- Use Python 3.11+ typing features +- Run `just mypy` to verify type correctness +- Strict mypy configuration is enforced + +## Pre-commit Hooks + +Pre-commit hooks are configured for: + +- ruff linting +- mypy type checking + +Run `just install` to set up hooks. + +## Essential Commands + +```bash +just install # Install dependencies and pre-commit hooks +just lint # Run ruff linting +just lint-fix # Auto-fix linting issues +just mypy # Run type checking +just test # Run all tests +just test-tools # Run tool-specific tests +just test-examples # Run example tests +``` + +## File Naming + +- Use snake_case for Python files +- Use `.yaml` extension instead of `.yml` for YAML files +- Keep file names concise but meaningful + +## Import Organisation + +- Standard library imports first +- Third-party imports second +- Local imports last +- Use absolute imports (see no-relative-imports rule) + +## Working with Tools + +- Use semantic tools for code exploration (avoid full file reads when possible) +- Leverage symbol indexing for fast navigation +- Use grep/ripgrep for pattern matching +- Read only necessary code sections diff --git a/.claude/rules/examples-standards.md b/.claude/rules/examples-standards.md new file mode 100644 index 0000000..4cd4f39 --- /dev/null +++ b/.claude/rules/examples-standards.md @@ -0,0 +1,75 @@ +--- +description: Standards for creating and maintaining examples for all functionality. (project) +globs: examples/**/* +paths: examples/**/* +--- + +# Examples Standards + +Standards for creating and maintaining examples in the StackOne repository. + +## Location Requirements + +``` +examples/ +├── basic_usage/ +│ ├── basic_tool_usage.py # Basic usage examples +│ └── error_handling.py # Error handling examples +├── integrations/ # Integration examples +│ ├── openai_integration.py +│ └── other_integration.py +└── README.md # Examples documentation +``` + +## Example Requirements + +- Every public function/class needs at least one example +- Examples should be runnable Python scripts +- Include error handling cases +- Load credentials from .env +- Include type hints +- Follow the same code style as the main codebase + +## Documentation + +- Each example file should start with a docstring explaining its purpose +- Include expected output in comments +- Document any prerequisites (environment variables, etc) + +## Testing + +- Examples should be tested as part of CI +- Examples should work with the latest package version +- Include sample responses in comments + +## Good Example Structure + +```python +import os +from dotenv import load_dotenv +from stackone_ai import StackOneToolSet + +def main(): + """Example showing basic usage of StackOneToolSet.""" + load_dotenv() + + api_key = os.getenv("STACKONE_API_KEY") + if not api_key: + raise ValueError("STACKONE_API_KEY not found") + + # Example code... + +if __name__ == "__main__": + main() +``` + +## Bad Example (avoid) + +```python +# Missing error handling, docs, types +from stackone_ai import StackOneToolSet + +toolset = StackOneToolSet("hardcoded_key") +tools = toolset.get_tools("crm") +result = tools["some_tool"].execute() +``` diff --git a/.claude/rules/git-workflow.md b/.claude/rules/git-workflow.md new file mode 100644 index 0000000..251f15c --- /dev/null +++ b/.claude/rules/git-workflow.md @@ -0,0 +1,97 @@ +--- +description: Git workflow, commit conventions, and pull request guidelines. (project) +alwaysApply: true +--- + +# Git Workflow + +This rule provides guidance on git workflow, commit conventions, and pull request guidelines. + +## Branch Strategy + +- **Never push directly to main** without permission +- Create a new branch for changes +- Create a pull request to merge into main +- Use `git switch -c feature-name` to start + +## Development Flow + +1. Create feature branch: `git switch -c feature-name` +2. Make changes to source files +3. Run linter: `just lint` +4. Run tests: `just test` +5. Fix linting issues: `just lint-fix` +6. Commit with detailed messages +7. Push and create PR: `gh pr create` + +## Commit Strategy + +Keep commits tiny but meaningful: + +- Use git hunks (`-p` flag) to selectively commit changes +- Write detailed commit messages +- Ensure each commit is logically complete +- Use English for all commit messages + +## Commit Message Format + +Format: `type(scope): description` + +Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `ci`, `perf` + +Example: + +``` +feat(parser): add support for custom parameter transformers + +- Add new transformer hooks to OpenAPI parser +- Enable pre-processing of tool parameters +- Implement docs for custom transformers +``` + +### Guidelines + +- Keep each commit as tiny as possible +- Write detailed commit messages explaining the "why" +- Each commit should be meaningful (not just a single line change) +- Use git hunks (`-p` flag) to selectively commit related changes +- **Always use English** for commit messages +- Reference issues and PRs when relevant + +### When Committing + +1. Run `git diff` to review all changes +2. Use `git add -p` to review and stage hunks selectively +3. Write comprehensive message explaining the purpose +4. Verify with `git status` before committing + +### File Moves for History Preservation + +When moving files (e.g., migrating from skills to rules), combine the deletion and creation in a single commit so git treats it as a rename. This preserves file history. + +```bash +# Instead of separate add/delete commits: +git add .claude/rules/new-file.md +git rm .claude/skills/old-file/SKILL.md +git commit -m "refactor(rules): migrate old-file to rules directory" +``` + +## Pull Request Guidelines + +### PR Title Format + +Use the same format as commit messages: `type(scope): description` + +Examples: + +- `feat(tools): add support for custom OpenAPI specs` +- `fix(parser): handle empty response bodies` +- `refactor(rules): unify cursor rules and claude rules` + +### PR Body + +Include: + +- **Summary**: 1-3 bullet points describing changes +- **Test plan**: How to verify the changes work +- Reference related issues with `Closes #123` or `Fixes #123` diff --git a/.claude/rules/no-relative-imports.md b/.claude/rules/no-relative-imports.md new file mode 100644 index 0000000..2e61e9b --- /dev/null +++ b/.claude/rules/no-relative-imports.md @@ -0,0 +1,27 @@ +--- +description: Enforce the use of absolute imports instead of relative imports in Python files. (project) +globs: "**/*.py" +paths: "**/*.py" +--- + +# No Relative Imports + +Standards for using absolute imports instead of relative imports in Python files. + +## Guidelines + +- Always use absolute imports starting with the full package name (`stackone_ai`) +- Never use relative imports (`.` or `..`) +- Keep imports organised and grouped + +## Examples + +```python +# Good - absolute imports +from stackone_ai.tools import ToolDefinition +from stackone_ai.constants import OAS_DIR + +# Bad - relative imports (don't use) +from .tools import ToolDefinition +from ..constants import OAS_DIR +``` diff --git a/.claude/rules/package-installation.md b/.claude/rules/package-installation.md new file mode 100644 index 0000000..020436c --- /dev/null +++ b/.claude/rules/package-installation.md @@ -0,0 +1,59 @@ +--- +description: Standards for installing packages with UV in StackOne. (project) +globs: "**/pyproject.toml" +paths: "**/pyproject.toml" +--- + +# Package Installation Standards + +Standards for installing packages with UV in the StackOne repository. + +## Root Level Dev Dependencies + +```bash +# Install dev dependencies at root level +uv add --dev pytest +uv add --dev pytest-cov +uv add --dev black +``` + +## Package Level Dependencies + +```bash +# Install package dependencies +uv add pydantic +uv add requests +``` + +## Never Use + +```bash +# ❌ Don't use pip install +uv pip install package-name + +# ❌ Don't use -e or editable installs +uv pip install -e . +``` + +## Running Tests + +```bash +# Run from root directory +uv run pytest + +# Run specific package tests +uv run pytest stackone_ai + +# Run tests on examples +uv run pytest examples +``` + +## Package Dependencies in pyproject.toml + +```toml +[project] +dependencies = [ + "pydantic>=2.10.6", + "requests>=2.32.3", +] +``` diff --git a/.claude/rules/release-please-standards.md b/.claude/rules/release-please-standards.md new file mode 100644 index 0000000..bf748eb --- /dev/null +++ b/.claude/rules/release-please-standards.md @@ -0,0 +1,63 @@ +--- +description: Standards for using release-please in the repository. (project) +alwaysApply: true +--- + +# Release Please Standards + +Standards for managing releases with release-please in the repository. + +## Configuration Files + +``` +.release-please-config.json # Release configuration +.release-please-manifest.json # Version tracking +.github/workflows/release.yml # Release workflow +``` + +## Commit Message Format + +```bash +# Features (0.1.0 -> 0.2.0) +feat: add new feature +feat!: breaking change feature + +# Bug Fixes (0.1.0 -> 0.1.1) +fix: bug fix description + +# No Version Change +docs: update readme +chore: update dependencies +test: add new tests +``` + +## Release Process + +1. Push to main branch triggers release-please +2. Release-please creates/updates release PR +3. Merging release PR: + - Updates CHANGELOG.md + - Creates GitHub release + - Publishes to PyPI using UV + +## Required Secrets + +``` +PYPI_API_TOKEN # For publishing to PyPI +``` + +## Good Commit Messages + +```bash +docs: update installation guide +fix: handle API timeout errors +feat: add new CRM integration +``` + +## Bad Commit Messages (avoid) + +```bash +updated readme +fixed bug in api +added feature +``` diff --git a/.claude/rules/uv-scripts.md b/.claude/rules/uv-scripts.md new file mode 100644 index 0000000..3ada016 --- /dev/null +++ b/.claude/rules/uv-scripts.md @@ -0,0 +1,66 @@ +--- +description: Standards for creating and managing utility scripts with UV. (project) +globs: scripts/**/*.py +paths: scripts/**/*.py +--- + +# UV Scripts Standards + +Standards for creating and managing utility scripts with UV. + +## Location + +- Place all utility scripts in the `scripts/` directory +- NOT for examples (use `examples/` directory instead) + +## UV Script Dependencies Header + +```python +# /// script +# requires-python = ">=3.8" +# dependencies = [ +# "package1", +# "package2>=1.0.0" +# ] +# /// +``` + +## Script Structure + +- Type hints are required +- Use async/await when doing I/O operations +- Include main guard: `if __name__ == "__main__":` +- Add return types to functions + +## Running Scripts + +```bash +uv run scripts/your_script.py +``` + +## Error Handling + +- Use try/except blocks for external calls +- Print meaningful error messages +- Exit with appropriate status codes + +## Example Script + +```python +# /// script +# requires-python = ">=3.8" +# dependencies = ["httpx"] +# /// + +from typing import Dict +import asyncio +import httpx + +async def fetch_data() -> Dict: + async with httpx.AsyncClient() as client: + response = await client.get("https://api.example.com") + return response.json() + +if __name__ == "__main__": + asyncio.run(fetch_data()) +``` diff --git a/.cursor/rules/cursor-rules-location.mdc b/.cursor/rules/cursor-rules-location.mdc deleted file mode 100644 index 4d1bd9f..0000000 --- a/.cursor/rules/cursor-rules-location.mdc +++ /dev/null @@ -1,75 +0,0 @@ ---- -description: Standards for placing Cursor rule files in the correct -globs: *.mdc ---- -# Cursor Rules Location - -Rules for placing and organizing Cursor rule files in the repository. - - -name: cursor_rules_location -description: Standards for placing Cursor rule files in the correct directory -filters: - # Match any .mdc files - - type: file_extension - pattern: "\\.mdc$" - # Match files that look like Cursor rules - - type: content - pattern: "(?s).*?" - # Match file creation events - - type: event - pattern: "file_create" - -actions: - - type: reject - conditions: - - pattern: "^(?!\\.\\/\\.cursor\\/rules\\/.*\\.mdc$)" - message: "Cursor rule files (.mdc) must be placed in the .cursor/rules directory" - - - type: suggest - message: | - When creating Cursor rules: - - 1. Always place rule files in PROJECT_ROOT/.cursor/rules/: - ``` - .cursor/rules/ - ├── your-rule-name.mdc - ├── another-rule.mdc - └── ... - ``` - - 2. Follow the naming convention: - - Use kebab-case for filenames - - Always use .mdc extension - - Make names descriptive of the rule's purpose - - 3. Directory structure: - ``` - PROJECT_ROOT/ - ├── .cursor/ - │ └── rules/ - │ ├── your-rule-name.mdc - │ └── ... - └── ... - ``` - - 4. Never place rule files: - - In the project root - - In subdirectories outside .cursor/rules - - In any other location - -examples: - - input: | - # Bad: Rule file in wrong location - rules/my-rule.mdc - my-rule.mdc - .rules/my-rule.mdc - - # Good: Rule file in correct location - .cursor/rules/my-rule.mdc - output: "Correctly placed Cursor rule file" - -metadata: - priority: high - version: 1.0 - \ No newline at end of file diff --git a/.cursor/rules/development-workflow.mdc b/.cursor/rules/development-workflow.mdc new file mode 120000 index 0000000..c9a352f --- /dev/null +++ b/.cursor/rules/development-workflow.mdc @@ -0,0 +1 @@ +../../.claude/rules/development-workflow.md \ No newline at end of file diff --git a/.cursor/rules/examples-standards.mdc b/.cursor/rules/examples-standards.mdc deleted file mode 100644 index 314c283..0000000 --- a/.cursor/rules/examples-standards.mdc +++ /dev/null @@ -1,89 +0,0 @@ ---- -description: Standards for creating and maintaining examples for all functionality -globs: examples/* ---- -# Examples Standards - -Standards for creating and maintaining examples in the StackOne repository. - - -name: examples_standards -description: Standards for creating and maintaining examples for all functionality - -filters: - - type: path - pattern: "^examples/.*" - -actions: - - type: suggest - message: | - When working with examples: - - 1. Location Requirements: - ``` - examples/ - ├── basic_usage/ - │ ├── basic_tool_usage.py # Basic usage examples - │ └── error_handling.py # Error handling examples - ├── integrations/ # Integration examples - │ ├── openai_integration.py - │ └── other_integration.py - └── README.md # Examples documentation - ``` - - 2. Example Requirements: - - Every public function/class needs at least one example - - Examples should be runnable Python scripts - - Include error handling cases - - Load credentials from .env - - Include type hints - - Follow the same code style as the main codebase - - 3. Documentation: - - Each example file should start with a docstring explaining its purpose - - Include expected output in comments - - Document any prerequisites (environment variables, etc) - - 4. Testing: - - Examples should be tested as part of CI - - Examples should work with the latest package version - - Include sample responses in comments - -examples: - - input: | - # Good example structure - import os - from dotenv import load_dotenv - from stackone_ai import StackOneToolSet - - def main(): - """Example showing basic usage of StackOneToolSet.""" - load_dotenv() - - api_key = os.getenv("STACKONE_API_KEY") - if not api_key: - raise ValueError("STACKONE_API_KEY not found") - - # Example code... - - if __name__ == "__main__": - main() - output: "Correctly structured example" - - - input: | - # Bad example - missing error handling, docs, types - from stackone_ai import StackOneToolSet - - toolset = StackOneToolSet("hardcoded_key") - tools = toolset.get_tools("crm") - result = tools["some_tool"].execute() - output: "Incorrectly structured example" - -metadata: - priority: high - version: 1.0 - tags: - - examples - - documentation - - testing - \ No newline at end of file diff --git a/.cursor/rules/examples-standards.mdc b/.cursor/rules/examples-standards.mdc new file mode 120000 index 0000000..762ca08 --- /dev/null +++ b/.cursor/rules/examples-standards.mdc @@ -0,0 +1 @@ +../../.claude/rules/examples-standards.md \ No newline at end of file diff --git a/.cursor/rules/git-workflow.mdc b/.cursor/rules/git-workflow.mdc new file mode 120000 index 0000000..6fb40d0 --- /dev/null +++ b/.cursor/rules/git-workflow.mdc @@ -0,0 +1 @@ +../../.claude/rules/git-workflow.md \ No newline at end of file diff --git a/.cursor/rules/no-relative-imports.mdc b/.cursor/rules/no-relative-imports.mdc deleted file mode 100644 index b361b74..0000000 --- a/.cursor/rules/no-relative-imports.mdc +++ /dev/null @@ -1,54 +0,0 @@ -# No Relative Imports - -Standards for using absolute imports instead of relative imports in Python files. - - -name: no_relative_imports -description: Enforce the use of absolute imports instead of relative imports in Python files -filters: - - type: file_extension - pattern: "\\.py$" - - type: content - pattern: "^from \\." - -actions: - - type: reject - conditions: - - pattern: "^from \\." - message: "Use absolute imports (from stackone_ai...) instead of relative imports" - - - type: suggest - message: | - When importing modules: - - 1. Always use absolute imports: - ```python - # Good - from stackone_ai.tools import ToolDefinition - from stackone_ai.constants import OAS_DIR - - # Bad - from .tools import ToolDefinition - from ..constants import OAS_DIR - ``` - - 2. Guidelines: - - Start imports with the full package name (stackone_ai) - - Never use relative imports (. or ..) - - Keep imports organized and grouped - -examples: - - input: | - # Bad: Using relative imports - from .tools import ToolDefinition - from ..constants import OAS_DIR - - # Good: Using absolute imports - from stackone_ai.tools import ToolDefinition - from stackone_ai.constants import OAS_DIR - output: "Correctly formatted absolute imports" - -metadata: - priority: high - version: 1.0 - \ No newline at end of file diff --git a/.cursor/rules/no-relative-imports.mdc b/.cursor/rules/no-relative-imports.mdc new file mode 120000 index 0000000..824830a --- /dev/null +++ b/.cursor/rules/no-relative-imports.mdc @@ -0,0 +1 @@ +../../.claude/rules/no-relative-imports.md \ No newline at end of file diff --git a/.cursor/rules/package-installation.mdc b/.cursor/rules/package-installation.mdc deleted file mode 100644 index d85adff..0000000 --- a/.cursor/rules/package-installation.mdc +++ /dev/null @@ -1,88 +0,0 @@ ---- -description: Standards for installing packages with UV in StackOne -globs: "**/pyproject.toml" ---- -# Package Installation Standards - - -name: package_installation -description: Standards for installing packages with UV in StackOne monorepo - -filters: - - type: file_extension - pattern: "\\.toml$" - - type: path - pattern: ".*pyproject\\.toml$" - -actions: - - type: suggest - message: | - When installing packages with UV: - - 1. Root Level Dev Dependencies: - ```bash - # Install dev dependencies at root level - uv add --dev pytest - uv add --dev pytest-cov - uv add --dev black - ``` - - 2. Package Level Dependencies: - ```bash - # Install package dependencies - uv add pydantic - uv add requests - ``` - - 3. Never use: - ```bash - # ❌ Don't use pip install - uv pip install package-name - - # ❌ Don't use -e or editable installs - uv pip install -e . - ``` - - 4. Running Tests: - ```bash - # Run from root directory - uv run pytest - - # Run specific package tests - uv run pytest stackone_ai - - #Run tests on examples - uv run pytest examples - ``` - - 5. Package Dependencies: - ```toml - # In package's pyproject.toml - [project] - dependencies = [ - "pydantic>=2.10.6", - "requests>=2.32.3", - ] - ``` - -examples: - - input: | - # Good: Installing dev dependencies at root - uv add --dev pytest - uv add --dev black - - # Good: Installing package dependencies - uv add pydantic - - # Bad: Using pip install - uv pip install -e ".[test]" - output: "Correctly installed packages with UV" - -metadata: - priority: high - version: 1.0 - tags: - - uv - - dependencies - - installation - \ No newline at end of file diff --git a/.cursor/rules/package-installation.mdc b/.cursor/rules/package-installation.mdc new file mode 120000 index 0000000..286b57d --- /dev/null +++ b/.cursor/rules/package-installation.mdc @@ -0,0 +1 @@ +../../.claude/rules/package-installation.md \ No newline at end of file diff --git a/.cursor/rules/release-please-standards.mdc b/.cursor/rules/release-please-standards.mdc deleted file mode 100644 index e1ddb59..0000000 --- a/.cursor/rules/release-please-standards.mdc +++ /dev/null @@ -1,77 +0,0 @@ ---- -description: Standards for using release-please in the repository -globs: "**/*" ---- -# Release Please Standards - -Standards for managing releases with release-please in the repository. - - -name: release_please_standards -description: Standards for using release-please for versioning and releases - -filters: - - type: path - pattern: ".*" - -actions: - - type: suggest - message: | - When working with releases: - - 1. Configuration Files: - ``` - .release-please-config.json # Release configuration - .release-please-manifest.json # Version tracking - .github/workflows/release.yaml # Release workflow - ``` - - 2. Commit Message Format: - ``` - # Features (0.1.0 -> 0.2.0) - feat: add new feature - feat!: breaking change feature - - # Bug Fixes (0.1.0 -> 0.1.1) - fix: bug fix description - - # No Version Change - docs: update readme - chore: update dependencies - test: add new tests - ``` - - 3. Release Process: - - Push to main branch triggers release-please - - Release-please creates/updates release PR - - Merging release PR: - 1. Updates CHANGELOG.md - 2. Creates GitHub release - 3. Publishes to PyPI using UV - - 4. Required Secrets: - ``` - PYPI_API_TOKEN # For publishing to PyPI - ``` - -examples: - - input: | - # Bad commit messages - updated readme - fixed bug in api - added feature - - # Good commit messages - docs: update installation guide - fix: handle API timeout errors - feat: add new CRM integration - output: "Correctly formatted commit messages" - -metadata: - priority: high - version: 1.0 - tags: - - release - - versioning - - git - \ No newline at end of file diff --git a/.cursor/rules/release-please-standards.mdc b/.cursor/rules/release-please-standards.mdc new file mode 120000 index 0000000..c7d3805 --- /dev/null +++ b/.cursor/rules/release-please-standards.mdc @@ -0,0 +1 @@ +../../.claude/rules/release-please-standards.md \ No newline at end of file diff --git a/.cursor/rules/uv-scripts.mdc b/.cursor/rules/uv-scripts.mdc deleted file mode 100644 index a35597d..0000000 --- a/.cursor/rules/uv-scripts.mdc +++ /dev/null @@ -1,83 +0,0 @@ ---- -description: Standards for creating and managing utility scripts with UV -globs: scripts/.* ---- -# UV Scripts Standards - - -name: uv_scripts -description: Standards for creating and managing utility scripts with UV - -filters: - - type: file_extension - pattern: "\\.py$" - - type: path - pattern: "^scripts/.*" - - type: exclude_path - pattern: "^(stackone_ai|examples)/.*" # Exclude package and examples - -actions: - - type: suggest - message: | - When creating utility scripts with UV: - - 1. Location: - - Place all utility scripts in the `scripts/` directory - - NOT for examples (use examples/ directory instead) - - 2. Include UV script dependencies header: - ```python - # /// script - # requires-python = ">=3.8" - # dependencies = [ - # "package1", - # "package2>=1.0.0" - # ] - # /// - ``` - - 3. Script Structure: - - Type hints are required - - Use async/await when doing I/O operations - - Include main guard: `if __name__ == "__main__":` - - Add return types to functions - - 4. Running Scripts: - ```bash - uv run scripts/your_script.py - ``` - - 5. Error Handling: - - Use try/except blocks for external calls - - Print meaningful error messages - - Exit with appropriate status codes - -examples: - - input: | - # Utility script - # /// script - # requires-python = ">=3.8" - # dependencies = ["httpx"] - # /// - - from typing import Dict - import asyncio - import httpx - - async def fetch_data() -> Dict: - async with httpx.AsyncClient() as client: - response = await client.get("https://api.example.com") - return response.json() - - if __name__ == "__main__": - asyncio.run(fetch_data()) - output: "Correctly structured utility script" - -metadata: - priority: high - version: 1.1 - tags: - - scripts - - uv - - python - \ No newline at end of file diff --git a/.cursor/rules/uv-scripts.mdc b/.cursor/rules/uv-scripts.mdc new file mode 120000 index 0000000..c90083e --- /dev/null +++ b/.cursor/rules/uv-scripts.mdc @@ -0,0 +1 @@ +../../.claude/rules/uv-scripts.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 7ecaaf0..ed57c5a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,13 +2,23 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. -## Cursor Rules +## Rules and Skills Structure -- @./.cursor/rules/package-installation -- @./.cursor/rules/no-relative-imports -- @./.cursor/rules/uv-scripts -- @./.cursor/rules/release-please-standards -- @./.cursor/rules/examples-standards +- **Rules** (`.claude/rules/`): Automatically loaded based on file paths. Source of truth for project conventions. +- **Skills** (`.claude/skills/`): Manually invoked for specific integrations. +- **Cursor rules** (`.cursor/rules/`): Symlinks to `.claude/rules/` for consistency. + +## Available Rules + +| Rule | Applies To | Description | +| ---------------------------- | ------------------- | -------------------------------------------------- | +| **git-workflow** | All files | Commit conventions, branch strategy, PR guidelines | +| **development-workflow** | All files | Code style, file naming, project conventions | +| **release-please-standards** | All files | Release versioning with release-please | +| **no-relative-imports** | `**/*.py` | Enforce absolute imports in Python files | +| **package-installation** | `**/pyproject.toml` | UV package management standards | +| **uv-scripts** | `scripts/**/*.py` | Utility script standards with UV | +| **examples-standards** | `examples/**/*` | Example requirements and organisation | ## Project Overview @@ -18,17 +28,17 @@ StackOne AI SDK is a Python library that provides a unified interface for access ```bash # Setup and installation -make install # Install dependencies and pre-commit hooks +just install # Install dependencies and pre-commit hooks # Code quality -make lint # Run ruff linting -make lint-fix # Auto-fix linting issues -make mypy # Run type checking +just lint # Run ruff linting +just lint-fix # Auto-fix linting issues +just mypy # Run type checking # Testing -make test # Run all tests -make test-tools # Run tool-specific tests -make test-examples # Run example tests +just test # Run all tests +just test-tools # Run tool-specific tests +just test-examples # Run example tests ``` ## Code Architecture @@ -85,11 +95,11 @@ toolset = StackOneToolSet( - Snapshot testing for tool parsing (`tests/snapshots/`) - Async tests use `pytest-asyncio` -- Example validation: See @./.cursor/rules/examples-standards +- See `examples-standards` rule for example validation ## Important Considerations -1. **Dependencies**: See @./.cursor/rules/package-installation for uv dependency management +1. **Dependencies**: See `package-installation` rule for uv dependency management 2. **Pre-commit**: Hooks configured for ruff and mypy - run on all commits 3. **Python Version**: Requires Python >=3.11 4. **Error Handling**: Custom exceptions (`StackOneError`, `StackOneAPIError`) @@ -104,7 +114,7 @@ toolset = StackOneToolSet( 2. Parser automatically converts to tool definitions 3. Test with `make test-tools` -### Modifying Tool Behavior +### Modifying Tool Behaviour - Core execution logic in `StackOneTool.execute()` method - HTTP configuration via `ExecuteConfig` class