britecore_sdk documentation

This site hosts generated API docs and key project guides.

Quick Navigation

This site is the canonical technical documentation for the SDK itself. If you need repo boundaries, ecosystem architecture, or cross-project workflow context, use the britecore_docs hub instead.

New to the SDK? Start here:

1. Getting Started — Installation and first API call (5 min)

2. Examples Overview — Runnable code examples

3. Common Patterns — Practical code patterns and recipes

4. Configuration — Setting up credentials and environments

5. Script-only data layer — Use models/normalizers without API calls

Looking for specific help?

• “How do I…?” → Common Patterns

• “How do I configure…?” → Configuration

• “Something broke” → Troubleshooting

• “I’m seeing DeprecationWarning messages” → 2.5.x migration guide

• “I’m upgrading from v1” → Migration Guide

• “I need an endpoint reference” → API Reference

• “How does this fit in the wider BriteCore stack?” → britecore_docs

Project Links

• GitHub repository: https://github.com/sshimek42/britecore_sdk

• Issue tracker: https://github.com/sshimek42/britecore_sdk/issues

• Releases: https://github.com/sshimek42/britecore_sdk/releases

• Changelog source: https://github.com/sshimek42/britecore_sdk/blob/master/CHANGELOG.md

---

Getting Started

• Project overview
  • Quick Start
  • Features
  • Migration Notes
  • Lightweight Data Layer for Scripts
  • Write Safety and Auditing
  • Documentation
  • Installation & Configuration
  • What This Package Provides
  • Using Async Wrappers
  • Development
  • Architecture
  • Support & Links
  • Project Links
• BriteCore SDK Examples
  • Quick Start Examples
  • Advanced Examples
  • Domain-Specific Examples
  • Setup Instructions
  • Running Examples
  • Pattern Reference
  • Common Tasks
  • Troubleshooting
  • Documentation Links

Learn by Doing

• Common patterns
  • Pattern 1: Policy Lookup with Fallback
  • Pattern 2: Batch Contact Import with Validation
  • Pattern 3: Rate Limit Aware Loops
  • Pattern 3b: Dry-Run Request Preview
  • Pattern 4: Pagination Through Large Result Sets
  • Pattern 5: Batch Operations with Progress Tracking
  • Pattern 6: Conditional Policy Updates
  • Pattern 7: Error Recovery with Retry
  • Pattern 8: Extract and Transform Responses
  • Pattern 9: Async Bulk Operations
  • Pattern 10: Context-Based Configuration
  • Tips and Best Practices
  • See Also
• Configuration Guide
  • Overview
  • Config Files
  • Loading Configuration
  • Environment Variables
  • Required Keys by Auth Mode
  • Optional Utility Keys
  • Validation
  • Per-Environment Setup
  • Troubleshooting
  • Adding New Sites
  • Private Maps Behavior
  • See Also
• Architecture roadmap
  • Overview
  • Breaking Changes & Migration Path
  • Implementation Timeline
  • Version Strategy
  • Testing Strategy
  • Documentation Updates
  • Success Metrics
  • See Also
• Response Caching Strategy
  • Overview
  • When to Enable Caching
  • Configuration
  • Cache Behavior
  • Performance Considerations
  • Caching Strategies
  • Troubleshooting
  • Best Practices
  • See Also
• Async Caching Guide
  • Where async wrappers live
  • Transport modes
  • Default behavior
  • Exact usage
  • Cache controls (RequestParameters)
  • Async dry-run behavior
  • Manage cache manually
  • Notes
• Optional extras
  • async-http — native async HTTP transport
  • typed-config — pydantic-validated settings view
  • interactive — menu-driven CLI utilities
  • Installing multiple extras
• Script-only data layer
  • Helpers
  • Quick example
  • CLI usage
  • When to use this vs API wrappers

How-To Guides

• Batch quote creation
  • Overview
  • Problem Statement
  • Quick Start
  • API Reference
  • Usage Patterns
  • Performance Tuning
  • Error Handling
  • Comparison: Sync vs. Async
  • Integration with Rate Limiting
  • Real-World Example: Nightly Batch Job
  • Troubleshooting
  • Performance Benchmarks
  • See Also
• Rate limiting
  • Overview
  • Why Use Rate Limiting?
  • Quick Start
  • Configuration
  • Configuration Parameters
  • How It Works
  • Logging
  • Monitoring Rate Limiter State
  • Advanced Usage
  • Best Practices
  • Comparison: Client-Side vs Server-Side Rate Limiting
  • Troubleshooting
  • See Also
• Events and webhooks
  • Overview
  • Core principles
  • Envelope and payload handling
  • Idempotency pattern
  • Retry coordination
  • Correlation and observability
  • Webhook framework and listener setup
  • Integration webhooks reference
  • Related SDK modules and docs
  • Practical checklist
• Multi-tenancy
  • Overview
  • Pattern 1: Module-Level Client with Reset (Simplest)
  • Pattern 2: Explicit Inline Credentials + Scoped use_api_client (Recommended)
  • Pattern 3: Context Manager for Isolated Operations
  • Pattern 4: Long-Lived Clients in a Service Registry
  • Pattern 5: Configuration File per Environment
  • Best Practices
  • Concurrent Multi-Tenancy with Async
  • Testing Multi-Tenancy
  • Common Patterns by Use Case
  • Troubleshooting
  • See Also
• Staged workflows
  • Why Staged Workflows?
  • Quick Start
  • Job Format
  • Result Format
  • Concurrency Parameters
  • fail_fast Behavior
  • Rate Limiting Integration
  • Adding New Stages
  • See Also
• Line extract stitching
  • Background: Why Stitching?
  • Important: Timeout Guidance
  • Quick Start
  • Line Tuple Format
  • Concurrency Guidance
  • Result Format
  • Error Handling
  • Single-Line Extract
  • See Also
• Implementation example
  • Overview
  • What Changed
  • Example Usage
  • Benefits
  • Technical Details
  • Testing
  • Files Modified/Created
  • Integration with Existing Code
  • Future Enhancements
  • Documentation
  • Metrics
  • Rollout Plan
  • Conclusion
• Observability
  • Overview
  • Logging Basics
  • X-SDK-Request-ID Headers
  • Debug Logging Levels
  • Authentication Mode Detection
  • Structured Logging with Context
  • Rate Limiting & Retry Observability
  • Audit Middleware
  • Async Cache Observability
  • Dry-Run Mode for Testing
  • Monitoring in Production
  • Correlation ID Propagation (Distributed Tracing)
  • Structured Logging with Categories (2.5.x+)
  • See Also

API Reference

• Overview
  • Notable SDK additions
  • Package exports
  • API clients
  • Exceptions
  • Utilities
  • V2 package exports
  • Workflow package exports
  • API Domains
• API Domains
  • Quotes and Policies APIs
  • Claims and Contacts APIs
  • Auto APIs
  • Spatial APIs
  • Financial and Operations APIs
  • Platform, Data, and Async APIs

Deployment & Operations

• Map Files
  • What britecore_sdk/maps/ now provides
  • Where mapping data now lives
  • Security policy (unchanged)
  • Adding a new carrier system
• Deployment & CI/CD Guide
  • Overview
  • Docker Deployment
  • Kubernetes Deployment
  • GitHub Actions CI/CD
  • AWS Lambda Deployment
  • Google Cloud Functions Deployment
  • GitLab CI/CD
  • Production Best Practices
  • Environment Variable Reference
  • Troubleshooting Deployment
  • See Also
• ReadTheDocs Versioning and Release Management
  • Overview
  • How versioning works
  • Creating a new release
  • RTD web interface
  • FAQ
  • Related documentation
• CI/CD and Coverage Guide
  • Overview
  • GitHub Actions Workflows
  • DeepSource Integration
  • Coverage Reports
  • Test Coverage Targets
  • Local Testing and Coverage
  • Troubleshooting CI
  • Best Practices
  • See Also
  • Bash Equivalents (Common Local Commands)
• Documentation Build Troubleshooting
  • Quick diagnostic checklist
  • Common documentation build errors
  • Prevention: Git hooks and pre-commit
  • Best practices for documentation changes
  • Running pre-commit in different scenarios
  • Related documentation
• Documentation Release Checklist
  • Release Docs Checklist
  • Minimal Release-Day Commands (PowerShell)
  • See Also
• Release Operations Checklist
  • Scope
  • PR Policy by Release Type
  • GitHub Admin Runbook: Branch Protection
  • Release Readiness Checklist
  • Minimal Release-Day Commands (PowerShell)
  • Ownership Sign-off Template
  • See Also
• Release Hotfix Template
  • Usage Rules
  • Hotfix Record
  • See Also
• 2.4.x Hotfix Contingency Runbook
  • Preconditions
  • Fast Path Checklist (2.4.9 Example)
  • Quick Rollback Options
  • See Also
• Solo Maintainer Merge Procedure
  • When to use this procedure
  • Recommended approach
  • Step-by-step
  • Suggested verification commands
  • Notes
• Branch Protection Baseline
  • Scope
  • Baseline Policy (Current)
  • Replay Commands
  • Verification Commands
  • Notes

Contributing & Policies

• Implementation checklist
  • Priority 1: Quick Wins
  • Priority 2: Developer Experience
  • Priority 3: Testing & Quality
  • Priority 4: Performance & Monitoring
  • Priority 5: Documentation & Examples
  • Priority 6: Advanced Features
  • Priority 7: Infrastructure & DevOps
  • Files Created (16 Total)
  • Files Modified (9 Total)
  • Validation Results
  • Installation & Verification
  • Next Steps for Users
  • Statistics
  • Quality Gate Status
• AGENTS Guide
• AGENTS.md
  • Scope and source of truth
  • Repo layout contract
  • Big-picture architecture
  • API module pattern (copy this when adding endpoints)
  • Docstring source policy
  • Configuration and integration points
  • Developer workflow in this repo
  • Logging
  • Pre-commit hooks and quality gates
  • Gotchas that affect agent changes
• Branch Hygiene Guide
  • Purpose
  • Branch Categories
  • Monthly 30-Second Cleanup
  • Safety Checks Before Force Deleting
  • Recommended Keep List
  • Recommended Delete List
  • Notes for Solo Maintainers

Reference & Migration

• Migration Guide: 2.4.x -> 2.5.x
• Migration Guide: SDK v1 -> v2 (Historical)
• POST Contract Probing
• Endpoint Verification Snapshot (2026-04-28)
• Reference Projects

---

Note

Documentation metadata

• Version: 2.5.1 | Built: 2026-09-24 (UTC) | Commit: e18a3b2f (2026-09-24)