Coding Style & Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• AGENTS.md
• pyproject.toml
• stackone_ai/types.py
• scripts/validate.sh
• stackone_ai/tools.py

This document defines the technical standards and development workflows for the StackOne AI Python SDK. These guidelines ensure consistency across the codebase, maintain high type safety, and enforce strict architectural boundaries between core logic and framework adapters.

The project follows a "served catalog" philosophy where schemas provided to AI models exactly match the schemas served by the Model Context Protocol (MCP) server. Developers must adhere to these patterns to maintain compatibility with supported AI frameworks like OpenAI, LangChain, and Pydantic AI.

Sources: CLAUDE.md:12-19, AGENTS.md:12-19

Development Workflow

The development lifecycle follows a strict sequence to ensure code quality and conformance. All changes must be branched and validated locally before submission.

Git and Pull Request Process

1. Branching: Create a new branch using git switch -c feature-name. Never push directly to the main branch.
2. Implementation: Apply changes following the modular architecture.
3. Formatting: Run make format to apply linting, formatting, and type checks.
4. Testing: Execute make test to run the full test suite.
5. Validation: Run make validate to check against conformance tests and third-party integrations.
6. Commit: Use the format type(scope): description. Supported types include feat, fix, docs, refactor, test, chore, ci, and perf.
7. PR Submission: Include a summary and a test plan. Reference issues using Closes #123.

Sources: CLAUDE.md:92-113, AGENTS.md:92-113, scripts/validate.sh:1-12

Validation Cycle

The following diagram illustrates the local validation flow required before committing code.

The validation script scripts/validate.sh executes static checks on examples, wire contract conformance, and consumer smoke tests for Google ADK and Pydantic AI.

Sources: scripts/validate.sh:122-137, CLAUDE.md:100-101

Code Style & Formatting

The project enforces strict Python standards using modern tooling to maintain a target version of Python 3.11.

• Linting and Formatting: Use ruff for all linting and code formatting tasks.
• Line Length: The maximum line length is set to 110 characters.
• Naming Conventions: Use snake_case for all Python filenames and identifiers.
• Conditionals: Favor early returns and guard clauses over deeply nested conditional blocks.
• File Extensions: Use .yaml for YAML files; do not use .yml.

Sources: CLAUDE.md:58-65, pyproject.toml:68-71, AGENTS.md:58-65

Import Standards

Always use absolute imports starting with the stackone_ai package name. Relative imports (e.g., from .tools import ...) are prohibited.

Order	Category	Example
1	Standard Library	import json
2	Third-party	import httpx
3	Local Package	from stackone_ai.tools import StackOneTool

Sources: CLAUDE.md:73-80, AGENTS.md:73-80

Type Annotations & Safety

Full type annotations are mandatory for all public APIs. The project utilizes Python 3.11+ typing features and generics to enhance IDE support and static analysis.

• Public APIs: Every function and class must include comprehensive type hints.
• JSON Handling: Use TypeAlias for common structures like JsonDict = dict[str, Any] and Headers = dict[str, str].
• Pydantic Models: Data structures like ToolParameters and ExecuteConfig must inherit from Pydantic's BaseModel for runtime validation.

Sources: stackone_ai/types.py:16-17, stackone_ai/types.py:145-171, CLAUDE.md:67-71

Architectural Constraints

The SDK architecture is divided into two distinct dependency tiers to prevent unnecessary overhead.

Dependency Management

• Core: Contains essential requirements (pydantic, httpx, mcp). This tier handles fetch_tools() and MCP communication.
• Extras: Contains framework adapters (langchain, pydantic-ai), examples, and development tools.

Lazy Loading Requirement: Framework adapters must be imported lazily within the specific method that requires them. A core installation must never pull in external frameworks.

Sources: pyproject.toml:21-55, CLAUDE.md:86-90, AGENTS.md:86-90

Module Responsibilities

The following class diagram represents the relationships between core modules.

• types.py: Defines the error hierarchy, shared aliases, and sanitization logic.
• tools.py: Implements execution logic, header sanitizing, and framework converters.
• toolset.py: Manages account discovery and the cached tool catalog.

Sources: CLAUDE.md:21-30, stackone_ai/tools.py:270-300, stackone_ai/types.py:1-12

Error Handling

All SDK exceptions must derive from the StackOneError base class. This hierarchy ensures that users can catch all project-specific errors with a single except StackOneError clause.

Exception Hierarchy

Class	Purpose
StackOneError	Base exception for all SDK errors.
StackOneAPIError	Raised when the StackOne API returns a non-success status code.
ToolsetError	Base exception for all toolset-related issues.
ToolsetConfigError	Raised for errors in SDK configuration.
ToolsetLoadError	Raised when tools fail to load via MCP.

Sources: stackone_ai/types.py:30-73, CLAUDE.md:120-124

Security & Sanitization

Security is enforced through strict allowlists and path sanitization.

• Header Sanitization: Only headers declared in the served schema are permitted. All other model-supplied headers are dropped to prevent lateral movement or credential leakage.
• Filename Sanitization: Server-supplied filenames from Content-Disposition headers are reduced to safe basenames. This prevents arbitrary file-write primitives by stripping traversal patterns (e.g., ../../) and control characters.
• Regex Matching: Use fullmatch instead of match for header grammar validation to prevent newline injection bypasses.

Sources: stackone_ai/types.py:108-143, stackone_ai/types.py:157-160, CLAUDE.md:127-133

Testing Standards

Testing is critical for maintaining MCP conformance.

• Async Testing: Use pytest-asyncio for all asynchronous tests.
• Mocks: Test doubles must strictly model server requirements. Fakes must refuse any request the real API would refuse (e.g., 400 for unscoped requests).
• Node Dependencies: Integration tests require the MCP mock server. Run pnpm install to ensure tests do not fail due to missing tsx or Node modules.
• Credential Handling: Load all credentials from a gitignored .env file. Never hardcode keys in the codebase or examples.

Sources: CLAUDE.md:43-56, CLAUDE.md:78-90, scripts/validate.sh:65-75

Summary

The StackOne AI Python SDK follows a modular, type-safe architecture centered on MCP-driven tool discovery. Developers must prioritize strict architectural boundaries, mandatory type annotations, and comprehensive local validation using the provided Makefile and validation scripts to maintain high code quality and security.