britecore_sdk documentation

This site hosts generated API docs and key project guides.

Quick Navigation

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

Looking for specific help?

• “How do I…?” → Common Patterns

• “How do I configure…?” → Configuration

• “Something broke” → Troubleshooting

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

• “I need an endpoint reference” → API Reference

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
  • 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

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 + 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
  • Async Cache Observability
  • Dry-Run Mode for Testing
  • Monitoring in Production
  • Correlation ID Propagation (Distributed Tracing)
  • Troubleshooting with Logs
  • 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

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

Reference & Migration

• Migration Guide: SDK v1 → v2
• POST Contract Probing
• Endpoint Verification Snapshot (2026-04-28)
• Reference Projects

---

Note

Documentation metadata

• Version: 2.2.0 | Built: 2026-07-24 (UTC) | Commit: ad8b9c4c (2026-07-24)