Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.2.0] - 2026-10-07

Explicit, cumulative same-process LangGraph continuation via compile_guarded_graph and GuardedGraph.resume, with checkpoint identity checks and independent run reports.
Original-ID tool-call cleanup for LangChain, OpenAI and Anthropic histories.
Additive report fields for run identity, continuation history, skipped tools and usage warnings.
Reproducible held-out detector evaluation, raw counts, latency and baseline comparison. Synthetic labels await human review; results are provisional.
Real framework contract tests, credential-free examples, compatibility documentation and version-matched release draft generation with executed check evidence.

Minimum supported Python version is now 3.11; package metadata, tooling and CI match.

OPEN remains terminal on clean observations; repeated recoveries retain their reflection limit.
Guarded synchronous, asynchronous and generator calls stop before body execution when the circuit is already OPEN; async/generator reset refreshes reports and reflection advice.
Excluded LangGraph tool nodes cannot dispatch after a trip.
Supported CrewAI synchronous ReAct executions receive recovery advice before the next model request, preserve callbacks, count complete actions once and use execution-scoped hooks.

Existing core imports, detector defaults, budget boundaries, report loading and optional extras are preserved. Reports are telemetry, not executable checkpoints.
Controlled graph resume supports one synchronous agent/tools cycle in the same process.
CrewAI execution support is explicitly bounded to the tested sequential ReAct executor. Unsupported execution modes fail clearly; callback-only CrewGuard remains available.
No stable release, PyPI publication, production savings or broad dependency-range claim.

CrewAI Integration (CrewGuard & add_guard_to_crew): Added native CrewAI support in longguard.integrations.crewai. Protects multi-agent crews from delegation loops and repetitive tool calls via step_callback and 1-line add_guard_to_crew(crew).
Universal @guarded Decorator: Added @guarded decorator in longguard.core.decorator (exported top-level as longguard.guarded). Wraps arbitrary Python functions, SDK calls, generators, and async coroutines with circuit breaker protection in 1 line.
PEP 561 Typing Support (py.typed): Added src/longguard/py.typed marker file and Typing :: Typed package classifier for strict IDE and static analysis support (MyPy, Pyright, VS Code Pylance).
CircuitBreakerTrippedError / CircuitBreakerError: Added explicit exception classes carrying reason, report, and decision for programmatic inspection when an agent is terminated.
Documentation & Theme Polish: Enhanced MkDocs configuration with logo, favicon, GitHub repository icon, back-to-top navigation, tab synchronization, social footer, and new documentation guides for CrewAI and the @guarded decorator.

PyPI Metadata & SEO Optimization: Updated official documentation URL to https://endevsols.github.io/LongGuard/, expanded keywords to 15 high-intent discovery tags, and added Operating System :: OS Independent and Topic :: System :: Monitoring classifiers.
README Links: Converted relative markdown links to absolute GitHub URLs to prevent 404 errors when rendered on PyPI.
Expanded Test Suite: Added 16 new test cases (271 tests total, 100% passing) covering @guarded (sync, async, generators, cost limits, fallbacks) and CrewGuard (action/finish parsing, crew wrapping, callback chaining).

Raw Client Integration (OpenAI & Anthropic): Added AgentStep.from_openai_response() and AgentStep.from_anthropic_response() class methods. Enables using LongGuard directly with standard openai and anthropic SDK client loops without requiring LangGraph or LangChain.
Dollar Cost Tracking: Built-in pricing engine (PRICING_TABLE, compute_cost, list_supported_models) supporting 40+ major LLM models (OpenAI GPT-4o/o1/o3, Anthropic Claude 3.5/4, Gemini 1.5/2.0/2.5, LLaMA 3.1/3.3, Mistral, Cohere).
Budget Hard Cap (max_cost_usd): Configure hard dollar spend limits on agent runs (max_cost_usd) to immediately trip the circuit breaker and prevent runaway API bills.
Custom Token Pricing Overrides: Added cost_per_input_token and cost_per_output_token in GuardConfig for private/fine-tuned or unlisted models.
Report Persistence (save / load): Persist telemetry to disk via report.save("run.json") and restore full state using GuardReport.load("run.json"). Supports JSON natively and YAML (when pyyaml is installed).
Runnable Examples & Docs: Added standalone example in examples/openai_raw_guard.py and documentation in docs/integrations/raw-client.md.

GuardReport Telemetry: GuardReport.summary() now displays Estimated Cost: $X.XXXX USD (model) when cost tracking is configured.
Expanded Test Suite: Added 76 new test cases (255 tests total, 100% passing) covering SDK response parsing, pricing calculations, breaker cost limits, and report serialization.
Automated GitHub Releases: Enhanced GitHub Actions workflow to parse release notes directly from CHANGELOG.md and exclude internal build metadata from release assets.

Dual-Theme Branding: Added dual-theme vector logos (logo-light.svg and logo-dark.svg) ensuring crystal-clear visibility across GitHub Dark, GitHub Light, and PyPI.
Clean Architecture Diagram: Replaced architecture diagram with high-contrast, professional SVG asset.
Contact Updates: Updated repository contact and security email addresses to technology@endevsols.com.
Branding Alignment: Refactored README and documentation to match the EnDevSols Long Suite design standards.

Initial Public Release of LongGuard: Production-grade in-flight circuit breaker for autonomous AI agents.
Circuit Breaker State Machine: 4-state lifecycle (CLOSED, REFLECTING, HALF_OPEN, OPEN).
4 Autonomous Loop Detectors:
ToolRepeatDetector: Identifies repetitive tool invocations with identical parameters.
SemanticOscillationDetector: Detects thought cycles and semantic loops using embedding variance.
DeadEndDriftDetector: Flags repeated empty, uninformative, or error-laden tool observations via Jaccard similarity.
TokenVelocityDetector: Monitors token consumption spikes against dynamic baselines.
Reflect & Pivot Recovery: Dynamic prompt injection mechanism that guides stuck agents out of loops before halting.
Framework Integrations:
LangGraph 1.0+ drop-in (add_guard_to_graph, LongGuard).
LangChain GuardedAgentExecutor wrapper.
Experimental Strands agent framework support (StrandsGuard).
Full Observability: Comprehensive telemetry and run analytics via GuardReport.
CI/CD & Documentation: Automated GitHub Actions test matrix across Python 3.10–3.12 and Material for MkDocs documentation site.