stackone-ai 0.3.3__tar.gz → 2.0.0__tar.gz

stackone_ai-2.0.0/.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 ty` to verify type correctness
+- Strict ty configuration is enforced
+
+## Pre-commit Hooks
+
+Pre-commit hooks are configured for:
+
+- ruff linting
+- ty 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 ty            # 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 Organization
+
+- 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

stackone_ai-2.0.0/.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()
+```

stackone_ai-2.0.0/.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`

stackone_ai-2.0.0/.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 organized 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
+```

stackone_ai-2.0.0/.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",
+]
+```

stackone_ai-2.0.0/.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
+```

stackone_ai-2.0.0/.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())
+```

stackone_ai-2.0.0/.cursor/rules/development-workflow.mdc

@@ -0,0 +1 @@
+../../.claude/rules/development-workflow.md

stackone_ai-2.0.0/.cursor/rules/examples-standards.mdc

@@ -0,0 +1 @@
+../../.claude/rules/examples-standards.md

stackone_ai-2.0.0/.cursor/rules/git-workflow.mdc

@@ -0,0 +1 @@
+../../.claude/rules/git-workflow.md

stackone_ai-2.0.0/.cursor/rules/no-relative-imports.mdc

@@ -0,0 +1 @@
+../../.claude/rules/no-relative-imports.md

stackone_ai-2.0.0/.cursor/rules/package-installation.mdc

@@ -0,0 +1 @@
+../../.claude/rules/package-installation.md

stackone_ai-2.0.0/.cursor/rules/release-please-standards.mdc

@@ -0,0 +1 @@
+../../.claude/rules/release-please-standards.md

stackone_ai-2.0.0/.cursor/rules/uv-scripts.mdc

@@ -0,0 +1 @@
+../../.claude/rules/uv-scripts.md

stackone_ai-2.0.0/.envrc

@@ -0,0 +1 @@
+use flake

stackone_ai-2.0.0/.github/actions/setup-nix/action.yaml

@@ -0,0 +1,19 @@
+name: "Setup Nix"
+description: "Install Nix and configure Cachix"
+runs:
+  using: "composite"
+  steps:
+    - name: Install Nix
+      uses: cachix/install-nix-action@0b0e072294b088b73964f1d72dfdac0951439dbd # v31.8.4
+      with:
+        github_access_token: ${{ github.token }}
+
+    - name: Setup Cachix (numtide)
+      uses: cachix/cachix-action@0fc020193b5a1fa3ac4575aa3a7d3aa6a35435ad # v16
+      with:
+        name: numtide
+        authToken: ""
+
+    - name: Load Nix development environment
+      shell: bash
+      run: nix develop --command true

stackone_ai-2.0.0/.github/dependabot.yaml

@@ -0,0 +1,58 @@
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+version: 2
+updates:
+  # Python dependencies (uv/pip)
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "09:00"
+      timezone: Europe/London
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: "chore(deps)"
+    labels:
+      - dependencies
+      - python
+    groups:
+      dev-dependencies:
+        patterns:
+          - "pytest*"
+          - "ruff"
+          - "ty"
+          - "pre-commit"
+        update-types:
+          - minor
+          - patch
+      ai-frameworks:
+        patterns:
+          - "openai*"
+          - "langchain*"
+          - "crewai*"
+          - "mcp*"
+        update-types:
+          - minor
+          - patch
+
+  # GitHub Actions
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "09:00"
+      timezone: Europe/London
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "chore(deps)"
+    labels:
+      - dependencies
+      - github-actions
+    groups:
+      actions:
+        patterns:
+          - "*"
+        update-types:
+          - minor
+          - patch

stackone_ai-2.0.0/.github/workflows/ci.yaml

@@ -0,0 +1,106 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  gitleaks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Setup Nix
+        uses: ./.github/actions/setup-nix
+
+      - name: Run Gitleaks
+        run: nix develop --command just gitleaks
+
+  ci:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.13"]
+        include:
+          - python-version: "3.11"
+            sync-extras: "--all-extras"
+          - python-version: "3.13"
+            sync-extras: "--all-extras"
+    env:
+      STACKONE_API_KEY: ${{ secrets.STACKONE_API_KEY }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Setup Nix
+        uses: ./.github/actions/setup-nix
+
+      - name: Install dependencies
+        run: nix develop --command just install ${{ matrix.sync-extras }}
+
+      - name: Run Lint
+        run: nix develop --command just lint
+
+      - name: Run Ty
+        run: nix develop --command just ty
+
+      - name: Run Tests
+        run: nix develop --command just test
+
+  coverage:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    env:
+      STACKONE_API_KEY: ${{ secrets.STACKONE_API_KEY }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Setup Nix
+        uses: ./.github/actions/setup-nix
+
+      - name: Install dependencies
+        run: nix develop --command just install --all-extras
+
+      - name: Run Tests with Coverage
+        run: nix develop --command just coverage
+
+      - name: Create Coverage Badge
+        uses: jaywcjlove/coverage-badges-cli@4e8975aa2628e3329126e7eee36724d07ed86fda # v2.2.0
+        with:
+          source: coverage/coverage.json
+          output: coverage/badges.svg
+          jsonPath: totals.percent_covered
+
+      - name: Upload coverage artifact
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v3.0.2
+        with:
+          path: coverage/
+
+  deploy-coverage:
+    needs: coverage
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5