Developer Environment & Setup

Relevant source files

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

• CLAUDE.md
• pyproject.toml
• package.json
• scripts/validate.sh
• README.md
• tests/mocks/serve.ts

The StackOne AI SDK developer environment consists of a Python 3.11+ core library and a TypeScript-based integration testing suite. The project uses uv for Python dependency management and make for task orchestration, while integration tests rely on pnpm to run a Model Context Protocol (MCP) mock server.

Sources: CLAUDE.md:12-14, README.md:144-150

Prerequisites and Dependencies

The SDK requires Python 3.11 or newer. Dependencies are categorized into core requirements for basic functionality and optional extras for framework adapters and development tools.

Python Dependency Tiers

Tier	Purpose	Key Packages
Core	Required for SDK function and MCP communication	pydantic, httpx, mcp
Extras (langchain)	Adapter for LangChain and LangGraph	langchain-core
Extras (pydantic-ai)	Adapter for Pydantic AI	pydantic-ai-slim
Extras (dev)	Testing, linting, and formatting	pytest, ruff, hypothesis, respx
Extras (examples)	Running example scripts	openai, python-dotenv

Sources: pyproject.toml:13-20, pyproject.toml:34-56, CLAUDE.md:95-103

Node.js Requirements

Integration tests utilize a mock MCP server written in TypeScript. You must install Node.js dependencies using pnpm to run these tests.

pnpm install

Sources: CLAUDE.md:120-123, package.json:8-16

Local Development Workflow

The project provides a Makefile to standardize common development tasks.

Core Commands

Command	Action
make install	Installs core dependencies only
make install extras=1	Installs core, adapters, examples, and dev tools
make format	Runs ruff to fix linting, formatting, and type checks
make test	Executes the full test suite
make validate	Runs conformance, SDK smoke tests, and example validation
make build	Builds the package

Sources: CLAUDE.md:54-61, README.md:150-160

Code Style Standards

• Linting & Formatting: Handled by ruff with a target line length of 110.
• Naming: Use snake_case for Python files.
• Imports: Always use absolute imports (e.g., from stackone_ai.tools import ...).
• Type Hints: Full type annotations are required for all public APIs.

Sources: CLAUDE.md:66-88, pyproject.toml:73-75

Testing Infrastructure

The testing environment combines unit tests and integration tests that simulate the StackOne API behavior.

MCP Mock Server Architecture

The mock server provides endpoints for both MCP protocol requests and RPC tool execution. It is built using Hono and runs via tsx.

The diagram shows how the Python test client interacts with the different endpoints exposed by the mock server during integration tests.

Sources: tests/mocks/serve.ts:39-65, CLAUDE.md:118-120

Validation Script

The scripts/validate.sh script performs comprehensive checks against external consumers and internal examples. It imports examples to ensure imports resolve and uses ty for type checking the function bodies of those examples.

The sequence diagram illustrates the multi-stage validation process used to ensure SDK compliance with the server contract and consumer frameworks.

Sources: scripts/validate.sh:37-77

Configuration and Credentials

Do not hardcode API keys. Use a gitignored .env file for local development.

1. Create a .env file in the project root.
2. Add STACKONE_API_KEY and STACKONE_ACCOUNT_ID.
3. Load the environment during script execution:

   uv run --env-file .env python your_script.py
   

Sources: CLAUDE.md:113-116, examples/auth_management.py:11-20

Release and Git Workflow

The project follows a branch-based development flow with automated releases.

1. Branching: Use git switch -c feature-name.
2. Commits: Use conventional commit formats (e.g., feat(scope): description).
3. PRs: Open a PR for review. Merging to main is restricted.
4. Releases: Managed by release-please. Merges to main trigger CHANGELOG.md updates and PyPI publishing.

Sources: CLAUDE.md:144-177

The developer environment is optimized for high technical accuracy, ensuring that served schemas reach the models intact by validating against a strict conformance suite before deployment.

Sources: CLAUDE.md:195-203