Configuration Reference

Relevant source files

• .gitignore
• .gitleaks.toml
• pyproject.toml
• stackone_ai/__init__.py

This page documents all configuration files in the StackOne AI SDK repository and their purposes. It provides an overview of how configuration is organized across package metadata, development tooling, and security policies.

For detailed information about specific configuration areas:

• Package dependencies and build configuration: see Package Configuration
• Development tool settings (ruff, pytest, ty, coverage): see Development Tools Configuration
• File exclusion and secret detection: see Security Configuration

Configuration File Overview

The SDK uses multiple configuration files organized by purpose and scope. The following diagram maps each configuration file to its primary role in the system:

Configuration File Locations

File	Path	Primary Purpose	Configuration Sections
pyproject.toml	Root directory	Package metadata, dependencies, tool settings	[project], [build-system], [tool.*]
uv.lock	Root directory	Locked Python dependencies with cryptographic hashes	Auto-generated by uv
.gitignore	Root directory	Files/directories excluded from version control	Pattern matching
.gitleaks.toml	Root directory	Secret scanning configuration	[extend], [allowlist]

Sources: pyproject.toml1-112 .gitignore1-24 .gitleaks.toml1-10

Configuration Layers

The SDK's configuration is organized into three distinct layers, each with different update mechanisms and responsibilities:

Layer 1: Package Definition

Defines what the package is, what it requires, and who maintains it. Modified during releases and dependency updates.

• Package metadata: pyproject.toml1-7 - name, version, description, authors
• Python version requirement: pyproject.toml6 - requires-python = ">=3.10"
• Runtime dependencies: pyproject.toml19-26 - pydantic, httpx, langchain-core, bm25s, numpy
• Optional dependencies: pyproject.toml38-46 - mcp and examples groups
• Development dependencies: pyproject.toml48-59 - pytest, ruff, ty, coverage tools

Layer 2: Build & Distribution

Controls how the package is assembled and published to PyPI. Rarely modified after initial setup.

• Build system declaration: pyproject.toml28-30 - uses hatchling backend
• Wheel configuration: pyproject.toml32-36 - packages only stackone_ai module
• Type stub inclusion: pyproject.toml35-36 - forces inclusion of py.typed marker file

Layer 3: Development Environment

Configures local development tools and testing infrastructure. Updated as coding standards evolve.

• Linting rules: pyproject.toml75-88 - line length, Python target, enabled checks
• Test configuration: pyproject.toml61-67 - async mode, test markers
• Coverage settings: pyproject.toml90-108 - source paths, exclusion patterns, output formats
• UV configuration: pyproject.toml110-111 - link-mode = "clone" for faster installs

Sources: pyproject.toml1-112

Configuration File Relationships

The following diagram shows how configuration files interact during different workflows:

Sources: pyproject.toml1-112 .gitignore1-24 .gitleaks.toml1-10

Core Configuration Sections

Project Metadata

Located at pyproject.toml1-18 defines package identity and compatibility:

Key Fields:

• name: Package identifier on PyPI (must match import name pattern)
• version: Semantic version, auto-updated by release-please
• requires-python: Minimum Python version (3.10+)
• classifiers: PyPI categories for discoverability

Dependency Specifications

The SDK uses three dependency mechanisms:

Mechanism	Section	Purpose	Example
Runtime dependencies	[project.dependencies]	Required for all users	pydantic>=2.10.6
Optional dependencies	[project.optional-dependencies]	Feature-specific extras	mcp = ["mcp>=1.3.0"]
Development groups	[dependency-groups.dev]	Dev tooling (PEP 735)	pytest>=8.3.4

Runtime dependencies at pyproject.toml19-26 use version constraints:

• pydantic>=2.10.6 - data validation and schema generation
• httpx>=0.28.0 - async HTTP client for API calls
• langchain-core>=0.1.0 - framework integration foundation
• bm25s>=0.2.2 - local semantic search (BM25 algorithm)
• numpy>=1.24.0 - numerical operations for search scoring

Optional dependencies at pyproject.toml38-46 enable additional features:

• mcp extra: MCP protocol support for advanced tool discovery
• examples extra: All frameworks for running example scripts (crewai, langchain-openai, langgraph, openai)

Sources: pyproject.toml19-46

Build System Configuration

Located at pyproject.toml28-36 configures package assembly:

Build Behavior:

• Uses hatchling as PEP 517 build backend (faster than setuptools)
• Only packages stackone_ai directory (excludes tests, examples)
• Force-includes py.typed marker for PEP 561 type stub distribution

Sources: pyproject.toml28-36

Tool-Specific Configurations

Each development tool has its own configuration section in pyproject.toml:

Ruff (Linting & Formatting) - pyproject.toml69-88

• Line length: 110 characters (wider than default 88 for readability)
• Target: Python 3.10 syntax
• Enabled checks: pycodestyle (E/W), pyflakes (F), isort (I), bugbear (B), comprehensions (C4), pyupgrade (UP)
• Per-file ignores: Relaxed rules for examples (allow print statements, long lines)

Pytest (Testing) - pyproject.toml61-67

• Async mode: strict (enforces proper async/await usage)
• Custom markers: @pytest.mark.integration for MCP-dependent tests

Coverage (Test Coverage) - pyproject.toml90-108

• Measures branch coverage (not just line coverage)
• Excludes: __init__.py (re-exports) and py.typed (marker file)
• Ignores: Type checking blocks and explicit no-cover pragmas
• Outputs: JSON (for badges) and HTML (for browsing)

UV (Package Manager) - pyproject.toml110-111

• Uses hard-link cloning for faster installs when possible
• Alternative to symlinks for better cross-platform compatibility

Sources: pyproject.toml61-111

Security Configuration

Git Ignore Patterns

Located at .gitignore1-24 excludes files from version control:

Environment & Secrets - .gitignore1-3

.env
.env.*
.venv

Prevents accidental commit of API keys and environment variables.

Build Artifacts - .gitignore14-16

*.egg-info
dist/
build/

Excludes generated files from package builds.

Test & Coverage - .gitignore5-9

.pytest_cache
.coverage
coverage/

Excludes test execution artifacts (coverage reports are deployed separately to GitHub Pages).

Managed Resources - .gitignore18-23

# Git hooks (managed by Nix)
.pre-commit-config.yaml

# Agent skills (managed by Nix via agent-skills-nix)
.claude/skills
.agents/skills

Excludes files managed by external systems (Nix flake manages these via agent-skills-nix).

Sources: .gitignore1-24

Secret Detection Configuration

Located at .gitleaks.toml1-10 configures Gitleaks secret scanner:

Configuration:

• useDefault = true: Uses Gitleaks' built-in secret patterns (AWS keys, GitHub tokens, etc.)
• paths allowlist: Excludes lock files and cache directories from scanning (false positives)

Integration:

• Runs as pre-commit hook (configured via Nix in git-hooks.nix)
• Runs in CI via .github/workflows/ci.yaml quality gates
• Blocks commits containing detected secrets

Sources: .gitleaks.toml1-10

Configuration Update Mechanisms

The following table summarizes how each configuration file is updated:

File	Update Method	Frequency	Automation
pyproject.toml (version)	release-please	On release	Automated via conventional commits
pyproject.toml (dependencies)	Manual or Dependabot PR	Weekly (Dependabot)	Semi-automated
pyproject.toml (tool configs)	Manual	As needed	Manual
uv.lock	uv lock, release-please	On dependency change, on release	Automated in release PRs
.gitignore	Manual	Rarely	Manual
.gitleaks.toml	Manual	Rarely	Manual

Automated Update Workflows:

1. Dependency updates: Dependabot creates weekly PRs for Python package updates to [project.dependencies]
2. Release updates: release-please updates version in pyproject.toml and regenerates uv.lock
3. Lock file updates: uv lock automatically regenerates uv.lock when pyproject.toml dependencies change

Sources: pyproject.toml1-112 Documentation from system architecture diagrams

Configuration Validation

The SDK includes multiple validation layers to ensure configuration correctness:

Pre-commit Validation:

• gitleaks: Scans for secrets before commit
• ruff format: Enforces code style from [tool.ruff]
• ty check: Validates type annotations

CI Validation:

• Test matrix: Runs pytest against Python 3.10-3.13 to validate requires-python
• nix flake check: Validates all Nix configuration (see Development Environment Setup)
• ruff check: Enforces linting rules from [tool.ruff.lint]

Sources: pyproject.toml61-111 .gitleaks.toml1-10

Quick Reference: Common Configuration Tasks

View Current Package Version:

Update Development Dependencies:

Check Configuration Syntax:

Add New Ignored File Pattern:

Test Secret Detection:

Sources: pyproject.toml1-112 .gitignore1-24 .gitleaks.toml1-10

---

For detailed configuration of specific subsystems:

• Package metadata and dependency specifications: see Package Configuration
• Development tool settings and quality standards: see Development Tools Configuration
• Security policies and exclusion rules: see Security Configuration
• Development environment setup using Nix: see Development Environment Setup
• Automated dependency updates: see Automated Dependency Updates