Skip to content

CLAUDE.md

Latest commit

 

History

History
106 lines (75 loc) · 4.44 KB

CLAUDE.md

File metadata and controls

106 lines (75 loc) · 4.44 KB

CLAUDE.md

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

Rules and Skills Structure

  • Rules (.claude/rules/): Automatically loaded based on file paths. Source of truth for project conventions.
  • Skills (.agents/skills/, .claude/skills/): Managed by Nix via agent-skills-nix. Skills are sourced from StackOneHQ/skills and installed automatically when entering nix develop.
  • Cursor rules (.cursor/rules/): Symlinks to .claude/rules/ for consistency.

Available Skills

Skill Usage Description
release-please /release-please <version> Trigger a release-please PR for a specific version

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
nix-workflow All files Nix development environment and CI configuration
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 organization

Available Skills

Skill Description
just-commands Available just commands (dynamically loaded)

Project Overview

StackOne AI SDK is a Python library that provides a unified interface for accessing various SaaS tools through AI-friendly APIs with support for OpenAI, LangChain, CrewAI, and Model Context Protocol (MCP).

Code Architecture

Core Components

  1. StackOneToolSet (stackone_ai/toolset.py): Main entry point

    • Handles authentication (API key + optional account ID)
    • Manages tool loading with glob pattern filtering
    • Provides format converters for OpenAI/LangChain

  2. Models (stackone_ai/models.py): Data structures

    • StackOneTool: Base class with execution logic
    • Tools: Container for managing multiple tools
    • Format converters for different AI frameworks

Key Development Patterns

Tool Filtering

# Use glob patterns for tool selection
tools = StackOneToolSet(include_tools=["bamboohr_*", "!bamboohr_create_*"])

Authentication

# Uses environment variables or direct configuration
toolset = StackOneToolSet(
    api_key="your-api-key",  # or STACKONE_API_KEY env var
    account_id="optional-id"  # explicit account ID required
)

Type Safety

  • Full type annotations required (Python 3.10+)
  • Strict ty configuration
  • Use generics for better IDE support

Testing

  • Snapshot testing for tool parsing (tests/snapshots/)
  • Async tests use pytest-asyncio
  • See examples-standards rule for example validation

Important Considerations

  1. Dependencies: See package-installation rule for uv dependency management
  2. Pre-commit: Hooks configured for ruff and ty - run on all commits
  3. Python Version: Requires Python >=3.10
  4. Error Handling: Custom exceptions (StackOneError, StackOneAPIError)
  5. File Uploads: Binary parameters auto-detected from OpenAPI specs
  6. Context Window: Tool loading warns when loading all tools (large context)

Common Tasks

Adding New SaaS Integration

  1. Add OpenAPI spec to stackone_ai/oas/
  2. Parser automatically converts to tool definitions
  3. Test with make test-tools

Modifying Tool Behavior

  • Core execution logic in StackOneTool.execute() method
  • HTTP configuration via ExecuteConfig class
  • Response handling in _process_response()