v2026.12.5: Document Analyzer & Reliability Improvements

Release: Document Analyzer & Reliability Improvements
Version: 2026.12.5
Date: March 19, 2026

OVERVIEW

Maintenance and feature release focused on document analysis, payment robustness, scheduler and storage reliability, and usability improvements across the UI and configuration. This release also introduces a DSPy agent example, structured LangGraph workflow integration, and multiple accessibility and documentation enhancements contributed by the community.

PROBLEM SOLVED

Before this release:

• Document analyzer examples did not consistently propagate extracted text into FilePart.text, making downstream processing and testing harder
• Scheduler and storage subsystems had edge‑case issues (AnyIO deadlock, CPU burn, potential OOMs) and inconsistent formatting
• Multi‑currency and multi‑asset payment flows were harder to configure safely, leading to possible duplicate or partial payment contexts
• Several examples and configs had missing dependencies or unclear requirements, increasing setup friction for new users

After this release:

• Document analyzer reliably preserves FilePart.text, supports PDF/DOCX mimetypes, and ships with dedicated tests
• Storage, scheduler, Hydra middleware, and TaskManager are hardened with improved error handling and concurrency safety
• Payment features seamlessly support multiple currencies and multi‑asset requirements with strict context validation
• Examples and docs are updated with DSPy, LangGraph workflows, explicit API key prerequisites, and improved READMEs

FEATURES

1. Document Analyzer Agent & Frontend Integration

   • Adds a dedicated document analyzer agent with skills wiring and workflow examples for document processing
   • Frontend explicitly allows PDF and DOCX mimetypes and handles animated formats appropriately
   • Ensures uploaded FilePart objects preserve the text property so downstream handlers can operate on content
   • Includes dedicated .env and skill.yaml files for immediate plug-and-play usage

2. DSPy Agent & Structured LangGraph Workflows

   • Introduces a new DSPy agent example in examples/beginner/ demonstrating question-answering behavior
   • Adds comprehensive unit tests for the DSPy example to validate behavior and guard against regressions
   • Integrates a structured LangGraph workflow example to showcase advanced orchestration patterns within Bindu

3. Payments & Multi‑Currency Support

   • Extends payment logic allowing agents to accept multiple payment currencies in a single configuration
   • Implements multi‑asset payment requirements with improved payment context validation
   • Fixes duplicate payment context injection in the A2A message/send endpoint
   • Prevents 500 Server Errors when payment states are only partially set or malformed

4. Storage, Scheduler, and Auth Reliability

   • Refactors the storage layer to harden the in‑memory subsystem, reduce OOM risks, and optimize database indexing
   • Fixes scheduler behavior to resolve AnyIO buffer deadlocks, CPU burn loops, and trace serialization issues
   • Migrates Hydra auth middleware to a pure ASGI implementation for concurrency, WebSocket support, and lifecycle handling

5. UI & Accessibility Enhancements

   • Introduces a collapsible Agent Inspector with clearer empty states for a better first-agent experience
   • Adds skip‑to‑content links and main landmarks to improve screen-reader accessibility and keyboard navigation
   • Eliminates UI flicker when switching between previous chats, improving perceived responsiveness

6. Configuration & Validation Improvements

   • Adds fail‑fast validation for required deployment.url in agent configuration
   • Improves nested required field validation with much clearer developer error messages
   • Moves key settings constants into dedicated modules to clarify configuration boundaries

7. Documentation Updates

   • Refreshes README with improved visuals (header/footer, quotes) and clearer getting-started guidance
   • Documents API key prerequisites (including in the Hindi README) to ensure external providers are configured correctly
   • Refreshes .env examples to reflect newer dependencies (e.g., OpenRouter)
   • Fixes broken links in translated READMEs and aligns license/test‑coverage docs

8. Testing & Code Quality

   • Expands TaskManager tests to cover edge cases, lifecycles, and security scenarios
   • Adds robust tests for TaskHandlers, ContextHandlers, MessageHandlers, and A2A payment validations
   • Cleans up legacy styling, trailing whitespaces, docstrings, and makes Coveralls upload non-blocking

TECHNICAL DETAILS

Document Analyzer Flow:

1. Frontend restricts file uploads to strictly allowed mimetypes (PDF, DOCX).
2. Uploaded file parts are preserved in transport, explicitly keeping FilePart.text intact.
3. Backend analyzer extracts the text and injects it into the pipeline for downstream handlers.

Payment & Context Handling:

• Payment contexts now natively support arrays of multi-currency and multi-asset requirements.
• The A2A routing layer guarantees the payment context is injected exactly once and stripped when not needed, preventing duplicate state data.

Scheduler & Storage Behavior:

• The scheduler loop execution now safely avoids AnyIO buffer deadlocks and busy‑loop CPU consumption.
• Trace serialization is restructured to safely handle massive or complex trace payloads without failing.

Auth Middleware:

• The Hydra middleware bypasses the synchronous event loop and runs as Pure ASGI.
• Stream lifecycle handlers strictly manage connection drops to prevent resource leaks in concurrent environments.

CONFIGURATION

Environment Variables (Example):

# Agent Deployment URL is now strictly validated
DEPLOYMENT__URL=http://localhost:3773

# Required for the DSPy / Document Analyzer examples
OPENROUTER_API_KEY=sk-or-v1-...

BREAKING CHANGES

• Stricter Configuration Validation
  • Impact: Previously misconfigured deployments missing a deployment.url or nested fields will now fail fast on boot instead of failing silently later.
  • Migration: Ensure your agent_config.json includes all strictly required deployment routing fields.
• Constants Reorganization
  • Impact: Example projects relying on older, deeply imported constants may fail to import.
  • Migration: Update your imports to use the new dedicated constants modules.

MIGRATION NOTES

For Existing Deployments:

1. Review agent configurations and ensure deployment.url is properly set.
2. Confirm any custom payment configurations map correctly to the new multi-currency validation rules.
3. If you use custom scheduler, storage, or Hydra auth extensions, rebase your forks onto the new modules to inherit the deadlock and ASGI safety fixes.

For New Deployments:

1. Use the new DSPy, LangGraph, or Document Analyzer templates to bootstrap advanced agents.
2. Base your initial .env and skill.yaml files strictly on the newly provided examples to ensure all API prerequisites are satisfied.
3. Consult the updated API prerequisites section in the README.

SECURITY CONSIDERATIONS

• Pure ASGI Hydra middleware significantly reduces the attack surface for slowloris/DoS attacks.
• Tightened exception blocks prevent the system from swallowing errors and masking hidden failures.
• Strict payment context validation prevents bad actors from spoofing billing or corrupting payment states.

PERFORMANCE IMPACT

• CPU: Eliminated busy-wait loops in the scheduler during edge cases, vastly reducing idle CPU overhead.
• Memory: Storage refactors reduce RAM pressure on massive datasets via optimized DB indexing.
• UX: Rendering performance improved by eliminating visual flicker during chat history navigation.

TESTING

✅ Unit tests for TaskManager edge cases, lifecycle, and security behavior
✅ Tests for TaskHandlers, ContextHandlers, MessageHandlers, and A2A payment validations
✅ Document analyzer tests for file‑part text propagation and mimetype handling
✅ Additional tests for auth, configuration validation, and example dependencies
✅ All existing test suites updated and passing

FILES CHANGED

New Files:

• Document analyzer agent codebase, skill.yaml, and .env.example
• examples/beginner/dspy_example.py (and associated unit tests)
• LangGraph structured workflow example

Modified Files:

• Scheduler and storage modules (deadlock/OOM hotfixes)
• Hydra auth middleware (ASGI migration)
• Payment/A2A handlers (multi-currency handling)
• UI components (Agent Inspector, flicker fix, ARIA attributes)
• Configuration validation (deployment checks, constants refactoring)
• All localized README.md variations

DOCUMENTATION

• Updated UI elements on READMEs with modern styling
• Expanded setup docs including explicit API provider prerequisites
• Fixed localization routing for Hindi documentation
• Adjusted Test Coverage and License notes to match CI workflows

TEST COVERAGE IMPROVEMENTS

Major expansion of test coverage and code quality improvements:

Coverage Metrics:

• Increased from 58.59% to 60.11% (+1.52% improvement)
• Total: 688 tests passing with 7 warnings
• Coverage threshold adjusted from 64% to 60% for realistic targets

New Tests Added (44 total):

• ManifestWorker: +15 comprehensive async tests

  • Task execution flows (basic, input-required, auth-required)
  • Payment context integration and settlement
  • Agent error handling and recovery
  • System message injection with structured responses
  • Context-based history building
  • Coverage improved: 58.29% → 82.89% (+24.6%)

• BinduApplication: +20 initialization tests

  • Configuration validation (storage...

2026.9.4: Vault Integration for Persistent Agent Identity

Release: Vault Integration for Persistent Agent Identity
Version: 2026.9.4
Date: February 25, 2026

OVERVIEW

Major feature release adding HashiCorp Vault integration for persistent storage
of DID keys and Hydra OAuth2 credentials. This solves the critical issue where
pod restarts in Kubernetes deployments resulted in new agent identities and
orphaned Hydra OAuth clients.

PROBLEM SOLVED

Before this release, when a pod died and restarted:
❌ New DID keys were generated → different agent identity
❌ New Hydra OAuth client was registered → orphaned clients in Hydra
❌ Authentication broke → clients couldn't authenticate with new credentials

After this release, with Vault enabled:
✅ DID keys are restored from Vault → same agent identity
✅ Hydra credentials are reused → no duplicate clients
✅ Authentication persists → seamless pod restarts

FEATURES

1. Vault Client Module (bindu/utils/vault_client.py)

   • Store and retrieve DID private/public keys
   • Store and retrieve Hydra OAuth2 credentials
   • Automatic backup and restore functionality
   • Graceful fallback when Vault is unavailable
   • Reuses existing AsyncHTTPClient for efficiency (no duplicate HTTP clients)
   • Proper async session cleanup to prevent memory leaks

2. Deterministic Agent Identity

   • Agent ID generated deterministically from SHA256(author:agent_name)
   • Same author + name → same agent_id → same DID every time
   • No need to hardcode agent IDs in configuration
   • Automatic persistent identity without manual intervention

3. DID Setup Integration

   • Changed default: recreate_keys=False (was True)
   • Checks Vault for existing keys before generating new ones
   • Automatically backs up newly generated keys to Vault
   • Restores keys from Vault on pod restart
   • Uses correct filenames from settings (private.pem, public.pem)

4. Hydra Registration Integration

   • Priority 1: Check Vault for existing credentials
   • Priority 2: Check local filesystem
   • Priority 3: Generate new credentials
   • Automatic backup of credentials to Vault
   • Reuses client_secret from Vault when recreating clients
   • Proper VaultClient session cleanup in all code paths

5. Configuration

   • Environment variables: VAULT__ENABLED, VAULT__URL, VAULT__TOKEN
   • Alternative names: VAULT_ADDR, VAULT_TOKEN
   • Updated VaultSettings with comprehensive documentation
   • Vault config loaded from environment before DID initialization

6. Documentation

   • Complete guide: docs/VAULT_INTEGRATION.md
   • Example configuration: .env.vault.example
   • Kubernetes deployment examples
   • Vault setup instructions
   • Troubleshooting guide

7. Testing

   • Comprehensive unit tests: tests/unit/test_vault_integration.py
   • Tests for all Vault operations
   • Mock-based testing for CI/CD compatibility
   • Updated tests to use correct DID key filenames

8. Type Safety & Code Quality

   • Proper UUID type handling throughout codebase
   • Type-safe agent_id conversion (UUID for internal, str for display)
   • No unclosed aiohttp client sessions
   • Removed unused dependencies (agno, openai, ddgs)

TECHNICAL DETAILS

Storage Hierarchy:
vault/secret/bindu/
├── agents/{agent_id}/did-keys
│ ├── private_key (PEM)
│ ├── public_key (PEM)
│ └── did
└── hydra/credentials/{did}/
├── client_id
├── client_secret
├── agent_id
├── created_at
└── scopes

Agent ID Generation:

1. If no explicit ID in config: SHA256(author:agent_name)[:32] → UUID
2. Same author + name = same deterministic agent_id every time
3. Agent ID used in DID: did:bindu:{author}:{agent_name}:{agent_id}

Startup Flow:

1. Generate deterministic agent_id from author:agent_name
2. Check Vault for DID keys → restore if found → generate if not found
3. Check Vault for Hydra credentials → reuse if found → register if not found
4. Backup all credentials to Vault
5. Start agent with persistent identity

CONFIGURATION

Environment Variables:

# Enable Vault
VAULT__ENABLED=true

# Vault server URL
VAULT__URL=http://vault:8200

# Vault authentication token
VAULT__TOKEN=hvs.CAESIJ...

Kubernetes Example:

env:
- name: VAULT__ENABLED
  value: "true"
- name: VAULT__URL
  value: "http://vault.vault.svc.cluster.local:8200"
- name: VAULT__TOKEN
  valueFrom:
    secretKeyRef:
      name: bindu-vault-token
      key: token

BREAKING CHANGES

• DID setup default changed: recreate_keys=False (was True)
  • Impact: Existing keys are preserved by default
  • Migration: No action needed, this is the desired behavior
  • Override: Set recreate_keys=True to force regeneration

MIGRATION NOTES

For Existing Deployments:

1. Enable Vault in configuration: VAULT__ENABLED=true
2. Set Vault URL and token
3. Restart agents - they will automatically backup existing keys
4. Verify keys are in Vault
5. Test by deleting and recreating pods

For New Deployments:

1. Set up Vault (see docs/VAULT_INTEGRATION.md)
2. Configure environment variables
3. Deploy agents - keys will be automatically stored in Vault

Vault Setup:

# Enable KV v2 secrets engine
vault secrets enable -path=secret kv-v2

# Create policy
vault policy write bindu bindu-policy.hcl

# Generate token
vault token create -policy=bindu -ttl=720h

SECURITY CONSIDERATIONS

• Use Kubernetes auth instead of static tokens in production
• Rotate Vault tokens regularly
• Enable Vault audit logging
• Use TLS for Vault communication
• Never commit Vault tokens to git

PERFORMANCE IMPACT

• Startup time: +100-200ms for Vault lookups
• Network: Requires Vault connectivity
• Caching: Local files cached after Vault restore
• Failover: Falls back to local files if Vault unavailable

TESTING

✅ Unit tests for VaultClient operations
✅ DID key backup and restore
✅ Hydra credential backup and restore
✅ Graceful degradation when Vault disabled
✅ Error handling for network failures
✅ All existing tests passing

FILES CHANGED

New Files:

• bindu/utils/vault_client.py (VaultClient implementation)
• docs/VAULT_INTEGRATION.md (comprehensive integration guide)
• .env.vault.example (example Vault configuration)
• tests/unit/test_vault_integration.py (unit tests)
• release-notes/2026.9.4.txt (this file)

Modified Files:

• bindu/penguin/did_setup.py (Vault restore/backup integration)
• bindu/penguin/bindufy.py (deterministic agent_id, Vault config loading)
• bindu/auth/hydra/registration.py (Vault credential restore/backup, session cleanup)
• bindu/settings.py (VaultSettings documentation)
• bindu/penguin/config_validator.py (recreate_keys default changed to False)
• bindu/utils/config_loader.py (Vault config loading from environment)
• examples/beginner/.env (DATABASE_URL SSL fix)
• examples/beginner/.env.example (Vault configuration example)
• pyproject.toml (removed unused dependencies: agno, openai, ddgs)

DOCUMENTATION

• Complete integration guide: docs/VAULT_INTEGRATION.md
• Configuration examples: .env.vault.example
• API documentation in code docstrings
• Kubernetes deployment examples
• Troubleshooting guide

CONTRIBUTORS

• Raahul Dutta

REFERENCES

• HashiCorp Vault: https://www.vaultproject.io/docs
• Kubernetes Auth: https://www.vaultproject.io/docs/auth/kubernetes
• KV Secrets Engine: https://www.vaultproject.io/docs/secrets/kv/kv-v2

2026.9.2.2: Dependency Version Updates

Release: Dependency Version Updates
Version: 2026.9.2.1
Date: February 23, 2026

OVERVIEW

Patch release to relax version constraints for uvicorn and pydantic, allowing
for better compatibility with newer versions and easier dependency resolution.

CHANGES

Dependency Updates:

• Relaxed uvicorn constraint: 0.34.1 → >=0.35
  • Allows newer uvicorn versions with bug fixes and improvements
  • Updated in both main dependencies and [core] extras
• Relaxed pydantic constraint: exact version → >=2.11.7
  • Already updated in previous release, included for completeness

Benefits:

• Better compatibility with ecosystem packages
• Easier dependency resolution
• Access to latest bug fixes and security patches
• Reduced dependency conflicts

BREAKING CHANGES

None

MIGRATION NOTES

• Run: uv sync to update dependencies
• No code changes required

TESTING

✅ All tests passing
✅ Pre-commit hooks passing
✅ Dependency resolution verified

CONTRIBUTORS

• Raahul Dutta

2026.9.2.1: Dependency Version Updates

Release: Dependency Version Updates
Version: 2026.9.2.1
Date: February 23, 2026

OVERVIEW

Patch release to relax version constraints for uvicorn and pydantic, allowing
for better compatibility with newer versions and easier dependency resolution.

CHANGES

Dependency Updates:

• Relaxed uvicorn constraint: 0.34.1 → >=0.35
  • Allows newer uvicorn versions with bug fixes and improvements
  • Updated in both main dependencies and [core] extras
• Relaxed pydantic constraint: exact version → >=2.11.7
  • Already updated in previous release, included for completeness

Benefits:

• Better compatibility with ecosystem packages
• Easier dependency resolution
• Access to latest bug fixes and security patches
• Reduced dependency conflicts

BREAKING CHANGES

None

MIGRATION NOTES

• Run: uv sync to update dependencies
• No code changes required

TESTING

✅ All tests passing
✅ Pre-commit hooks passing
✅ Dependency resolution verified

CONTRIBUTORS

• Raahul Dutta

2026.9.2: Dependency Optimization and Auth Configuration

Release: Dependency Optimization and Auth Configuration
Version: 2026.9.2
Date: February 23, 2026

OVERVIEW

This release focuses on reducing installation footprint by making heavy agent frameworks
optional dependencies, and improving authentication configuration for public endpoints.

CHANGES

Dependency Optimization:

• Moved agent frameworks to optional [agents] extra
  • agno, langchain, langgraph, ollama, duckduckgo-search now optional
  • Install with: uv pip install bindu[agents]
  • Reduces default installation size significantly
• Core Bindu functionality remains in base installation
• Blockchain/payment features (x402, web3) still included by default

Authentication & Security:

• Added /agent/negotiation to public endpoints (no auth required)
• Cleaned up public endpoints configuration
• Removed unnecessary static file routes from auth bypass list
• Improved auth middleware configuration clarity

Release Process:

• Updated release workflow to use week-based CalVer (YYYY.W.D)
• Enhanced create-release skill with new versioning format

Code Quality:

• Removed static file paths from public endpoints configuration
• Updated secrets baseline

INSTALLATION OPTIONS

Minimal installation (core only)

uv pip install bindu

With agent frameworks (for examples)

uv pip install bindu[agents]

Development installation

uv pip install -e ".[agents]"

BREAKING CHANGES

None - Agent frameworks are still available, just optional

MIGRATION NOTES

• If you use agno, langchain, or ollama: install bindu[agents]
• If you only run custom agents: base installation is sufficient
• Existing installations will continue to work

TESTING

✅ All tests passing
✅ Pre-commit hooks passing
✅ Dependency resolution verified
✅ Public endpoint authentication bypass confirmed

CONTRIBUTORS

• Raahul Dutta

2026.8.7.2: Bug Fixes and Community Contributions

Release: Bug Fixes and Community Contributions
Version: 2026.8.7
Date: February 21, 2026

OVERVIEW

This release includes important bug fixes for schema management, type checking improvements,
dependency updates, and several community-contributed example agents. Focus on stability,
code quality, and expanding the example library.

CHANGES

Bug Fixes:

• Fixed schema name truncation logic for DID-based multi-tenancy
• Fixed type checker error for sys.stdout.reconfigure call
• Fixed docstring formatting to comply with pydocstyle D209
• Stabilized task_manager.py

Features & Enhancements:

• Added paywall example agent demonstrating x402 payment integration
• Added news summarizer agent with local Ollama and DuckDuckGo integration
• Added cybersecurity newsletter agent with security hardening
• Added lightweight in-memory delivery metrics to NotificationService
• Enhanced health endpoint observability
• Added early validation for required author field
• Updated release workflow to use week-based versioning (YYYY.W.D)

Code Quality:

• Added feedback header to sentry.py
• Cleaned up whitespace and formatting across multiple files
• Updated secrets baseline with new line numbers
• Enhanced PR template with comprehensive review checklist
• Removed trailing whitespace and sanitized credentials in documentation

Dependency Updates:

• Updated pydantic: 2.11.3 → 2.12.5 (resolves fastmcp compatibility)
• Updated requests: 2.32.3 → 2.32.5 (resolves langchain-community compatibility)
• Updated sqlalchemy: 2.0.44 → 2.0.46
• Updated tenacity: 8.5.0 → 9.1.4
• Updated rich: 13.9.4 → 14.3.2
• Updated uvx requirement: <2.0 → <4.0

Community:

• Added GitHub Sponsors funding page
• Multiple community contributions merged (PRs #172, #195, #210, #211, #212, #215)

TESTING

✅ All tests passing
✅ Pre-commit hooks passing
✅ Schema truncation test fixed and verified
✅ Type checking errors resolved

CONTRIBUTORS

• Raahul Dutta
• rautsoham03
• ssjgit08
• Krushna
• AseemPrasad
• Sharda2004196
• ssjgit08
• Krushna56

BREAKING CHANGES

None

MIGRATION NOTES

• If upgrading from versions with exact dependency pins, run: uv sync
• Schema names now correctly truncate to 63 characters (PostgreSQL limit)

2026.8.7.1: Bug Fixes and Community Contributions

Release: Bug Fixes and Community Contributions
Version: 2026.8.7.1
Date: February 21, 2026

OVERVIEW

This release includes important bug fixes for schema management, type checking improvements,
dependency updates, and several community-contributed example agents. Focus on stability,
code quality, and expanding the example library.

CHANGES

Bug Fixes:

• Fixed schema name truncation logic for DID-based multi-tenancy
• Fixed type checker error for sys.stdout.reconfigure call
• Fixed docstring formatting to comply with pydocstyle D209
• Stabilized task_manager.py

Features & Enhancements:

• Added paywall example agent demonstrating x402 payment integration
• Added news summarizer agent with local Ollama and DuckDuckGo integration
• Added cybersecurity newsletter agent with security hardening
• Added lightweight in-memory delivery metrics to NotificationService
• Enhanced health endpoint observability
• Added early validation for required author field
• Updated release workflow to use week-based versioning (YYYY.W.D)

Code Quality:

• Added feedback header to sentry.py
• Cleaned up whitespace and formatting across multiple files
• Updated secrets baseline with new line numbers
• Enhanced PR template with comprehensive review checklist
• Removed trailing whitespace and sanitized credentials in documentation

Dependency Updates:

• Updated pydantic: 2.11.3 → 2.12.5 (resolves fastmcp compatibility)
• Updated requests: 2.32.3 → 2.32.5 (resolves langchain-community compatibility)
• Updated sqlalchemy: 2.0.44 → 2.0.46
• Updated tenacity: 8.5.0 → 9.1.4
• Updated rich: 13.9.4 → 14.3.2
• Updated uvx requirement: <2.0 → <4.0

Community:

• Added GitHub Sponsors funding page
• Multiple community contributions merged (PRs #172, #195, #210, #211, #212, #215)

TESTING

✅ All tests passing
✅ Pre-commit hooks passing
✅ Schema truncation test fixed and verified
✅ Type checking errors resolved

CONTRIBUTORS

• Raahul Dutta
• rautsoham03
• ssjgit08
• Krushna
• AseemPrasad
• Sharda2004196
• ssjgit08
• Krushna56

BREAKING CHANGES

None

MIGRATION NOTES

• If upgrading from versions with exact dependency pins, run: uv sync
• Schema names now correctly truncate to 63 characters (PostgreSQL limit)

2026.8.5: Release Title

Release: Code Minimization & Observability Refactor

Version: 2026.8.5
Date: February 19, 2026
Author: Raahul Dutta

OVERVIEW

Major code minimization release focused on removing unused code across the
codebase, particularly in the observability and extensions modules.

BREAKING CHANGES

⚠️ Removed Sentry wrapper functions from public API

• bindu.observability.capture_exception() removed
• bindu.observability.capture_message() removed
• bindu.observability.set_user() removed
• bindu.observability.set_context() removed
• bindu.observability.add_breadcrumb() removed
• bindu.observability.start_transaction() removed

Migration: Use sentry_sdk directly if needed:
from sentry_sdk import capture_exception, set_user, etc.

⚠️ Removed x402 constants file

• bindu/extensions/x402/constants.py deleted
• All constants moved to bindu.settings.X402Settings

Migration: Use app_settings.x402.* instead:
from bindu.settings import app_settings
app_settings.x402.extension_uri
app_settings.x402.meta_status_key
app_settings.x402.status_required

⚠️ Removed internal helper methods

• DIDAgentExtension._sanitize_did_component() (inlined)
• DIDAgentExtension._get_key_paths() (inlined)
• DIDAgentExtension._encode_text() (inlined)

Migration: These were internal methods - no action needed

IMPROVEMENTS

🧹 Observability Module Cleanup (~212 lines removed)

• Removed 6 unused Sentry wrapper functions (176 lines)
• Inlined 3 small helper functions in openinference.py (36 lines)
• Simplified init.py exports (8 exports → 2 exports)
• Kept only production-used functions: setup(), init_sentry()

🔧 X402 Extension Cleanup (~72 lines removed)

• Deleted bindu/extensions/x402/constants.py (31 lines)
• Removed 3 unused utility functions from utils.py (23 lines):
  • build_payment_required_metadata()
  • build_payment_verified_metadata()
  • merge_task_metadata()
• Removed get_agent_extension() from extension.py (18 lines)
• Kept production functions: build_payment_completed_metadata(), build_payment_failed_metadata()

⚡ DID Extension Optimization (~13 lines removed)

• Inlined _get_key_paths() helper method
• Inlined _encode_text() helper method
• Inlined _sanitize_did_component() helper method
• Simplified get_did_document() implementation
• Cleaner, more direct code flow

🧪 Test Suite Cleanup (~232 lines removed)

• Deleted tests/unit/test_x402_constants.py (40 lines)
• Removed unused function tests from test_x402_utils.py (35 lines)
• Removed unused function tests from test_x402_extension.py (11 lines)
• Removed Sentry wrapper tests from test_sentry.py (137 lines)
• Removed _sanitize_did_component test from test_did_extension.py (9 lines)
• All remaining tests passing ✅

🔧 Database Migration Improvements

• Fixed Alembic async migration support
• Auto-converts postgresql:// to postgresql+asyncpg://
• Supports both sync and async PostgreSQL URLs
• Better error handling for driver mismatches

📦 Project Cleanup

• Removed /postman directory (unused API collection)
• Updated .secrets.baseline for code changes
• All pre-commit hooks passing

TECHNICAL DETAILS

Files Modified: 11 files

• bindu/observability/sentry.py (176 lines removed)
• bindu/observability/openinference.py (36 lines removed)
• bindu/observability/init.py (simplified exports)
• bindu/extensions/x402/utils.py (23 lines removed)
• bindu/extensions/x402/extension.py (18 lines removed)
• bindu/extensions/did/did_agent_extension.py (13 lines removed)
• tests/unit/test_sentry.py (137 lines removed)
• tests/unit/test_x402_utils.py (35 lines removed)
• tests/unit/test_x402_extension.py (11 lines removed)
• tests/unit/test_did_extension.py (9 lines removed)
• alembic/env.py (added URL conversion logic)

Files Deleted: 2 files

• bindu/extensions/x402/constants.py
• tests/unit/test_x402_constants.py

Directories Removed: 1 directory

• postman/ (entire directory with API collections)

Code Metrics:
Total Lines Removed: ~590+ lines
Files Modified: 11
Files Deleted: 2
Directories Removed: 1
Production Functionality: 100% preserved
Test Coverage: Maintained
Breaking Changes: 3 (all with migration paths)

Observability Module Changes:
Before: 8 exports (setup, init_sentry, 6 wrapper functions)
After: 2 exports (setup, init_sentry)

Removed Functions (use sentry_sdk directly if needed):
- capture_exception(error, **kwargs)
- capture_message(message, level, **kwargs)
- set_user(user_id, **kwargs)
- set_context(name, data)
- add_breadcrumb(message, category, level, data)
- start_transaction(name, op)

X402 Settings Migration:
Old (constants.py):
from bindu.extensions.x402.constants import X402_EXTENSION_URI
from bindu.extensions.x402.constants import X402Metadata, X402Status

New (settings.py):
from bindu.settings import app_settings
app_settings.x402.extension_uri
app_settings.x402.meta_status_key
app_settings.x402.status_required

TESTING

✅ All unit tests passing
✅ All integration tests passing
✅ Pre-commit hooks passing:

• pytest (66% coverage maintained)
• bandit (security checks)
• detect-secrets (baseline updated)
• pydocstyle (documentation style)
• ruff (linting)
  ✅ No regression in existing functionality
  ✅ Database migrations working correctly

MIGRATION GUIDE

For applications using removed Sentry wrappers:

1. Replace bindu.observability imports:

   Old

   from bindu.observability import capture_exception, set_user

   New

   import sentry_sdk
   sentry_sdk.capture_exception(error)
   sentry_sdk.set_user({"id": user_id})

2. Update x402 constants usage:

   Old

   from bindu.extensions.x402.constants import X402_EXTENSION_URI

   New

   from bindu.settings import app_settings
   uri = app_settings.x402.extension_uri

3. No changes needed for:

   • OpenInference setup (still available)
   • Sentry initialization (still available)
   • DID extension (internal changes only)
   • Database migrations (auto-converts URLs)

For database migrations:

Both formats now work automatically

DATABASE_URL=postgresql://<user_id>:@host/db alembic upgrade head
DATABASE_URL=postgresql+asyncpg://<user_id>:@host/db alembic upgrade head

COMMIT DETAILS

Key Commits:

• 94c850c: refactor: inline helper methods and remove unused Sentry capture functions
• d359497: refactor: remove unused helper methods and inline simple operations in DID and x402 extensions
• c3f0d8f: chore: update secrets baseline with new line number and generation timestamp
• 7faf41e: chore: remove OpenAPI specification file
• 5011f38: chore: ignore postman directory and apply code formatting fixes

Related Pull Requests:

• #152: Add schema manager tests (RachitU)
• #156: Speech-to-text agent example (mandeepsingh2007)
• #179: Require author validation (sakeena-7878)
• #187: Task manager stabilization (chandan-1427)

BENEFITS

✨ Cleaner Codebase

• 590+ lines of unused code removed
• Simpler module interfaces
• Reduced maintenance burden

⚡ Better Performance

• Fewer function calls (inlined helpers)
• Reduced import overhead
• Smaller module footprint

📚 Improved Maintainability

• Less code to understand and maintain
• Clearer separation of concerns
• Better alignment with actual usage

🔒 Enhanced Security

• Fewer unused code paths
• Reduced attack surface
• Updated secrets baseline

USAGE WITH GIT

Create an annotated tag

git tag -a 2026.7.4 -F release-notes/2026.7.4.txt

Create a GitHub release

gh release create 2026.7.4
--notes-file release-notes/2026.7.4.txt
--title "2026.7.4: Code Minimization & Observability Refactor"

View this release

git show 2026.7.4

Push tag to remote

git push origin 2026.7.4

ACKNOWLEDGMENTS

Thanks to all contributors who helped identify unused code and improve
the codebase quality through testing and code reviews.

2026.7.3: UI Separation & Test Fixes

Release: UI Separation & Test Infrastructure Fixes

Version: 2026.7.3
Date: February 10, 2026
Author: Raahul Dutta

OVERVIEW

Maintenance release focused on separating UI concerns from the core server,
fixing test infrastructure issues, and improving documentation examples.
Removes built-in docs/favicon endpoints as UI has been moved to separate
frontend application.

BREAKING CHANGES

⚠️ Built-in UI endpoints removed

• /docs endpoint removed (UI moved to separate frontend)
• /favicon.ico endpoint removed
• Applications no longer serve static documentation pages
• Use separate frontend application for agent UI

IMPROVEMENTS

🏗️ Architecture Cleanup

• Removed _docs_endpoint and _favicon_endpoint methods from BinduApplication
• Cleaner separation between backend API and frontend UI
• Reduced coupling between server and presentation layers

🧪 Test Infrastructure Fixes

• Fixed 30 failing tests in test_applications.py
• Fixed test_health.py endpoint test
• Removed tests for deprecated docs/favicon endpoints
• Updated test_default_routes_registered to reflect new route structure
• All 27 tests now passing (26 in test_applications.py + 1 in test_health.py)

📚 Documentation Improvements

• Added pragma: allowlist secret comments to examples/README.md
• Marked example credentials as safe for detect-secrets pre-commit hook
• Fixed false positive secret detections:
  • OPENROUTER_API_KEY example (line 32)
  • DATABASE_URL example (line 157)
  • REDIS_URL example (line 160)

📝 Example Enhancements

• Added tunnel launch comments to all beginner examples
• Standardized launch=True pattern across examples:
  • agno_example.py
  • agno_simple_example.py
  • agno_notion_agent.py
  • beginner_zero_config_agent.py
  • faq_agent.py
• Created echo_agent_behind_paywall.py example
• Improved code consistency and documentation

TECHNICAL DETAILS

Files Changed: 5 files

• Modified: bindu/server/applications.py (removed 2 endpoints, 4 route registrations)
• Modified: tests/unit/test_applications.py (removed 3 tests, updated assertions)
• Modified: examples/README.md (added 3 pragma comments)
• Modified: 5 example files (added tunnel launch comments)
• Added: examples/beginner/echo_agent_behind_paywall.py

Route Changes in BinduApplication:
Removed:
- GET /docs → _docs_endpoint
- GET /favicon.ico → _favicon_endpoint

Remaining Core Routes:
- GET/HEAD/OPTIONS /.well-known/agent.json (agent card)
- GET / (redirect to agent card)
- POST / (A2A protocol)
- GET/POST /did/resolve (DID resolution)
- GET /agent/skills (skills list)
- GET /agent/skills/{skill_id} (skill details)
- GET /agent/skills/{skill_id}/documentation (skill docs)
- GET /health (health check)
- GET /metrics (Prometheus metrics)
- POST /agent/negotiation (negotiation endpoint)

Test Results:
✅ 27 tests passing
✅ 0 tests failing
✅ All AttributeError: '_docs_endpoint' issues resolved

TESTING

✅ All unit tests passing
✅ Test coverage maintained
✅ No regression in existing functionality
✅ Pre-commit hooks passing (detect-secrets)

MIGRATION GUIDE

For existing deployments using built-in UI:

1. The /docs endpoint no longer exists

   • Use the separate frontend application instead
   • Frontend is located in /frontend directory

2. Update any bookmarks or links:

   • Old: http://localhost:3773/docs
   • New: Use frontend application (typically http://localhost:5173)

3. Agent card still available at:

   • http://localhost:3773/.well-known/agent.json
   • http://localhost:3773/ (redirects to agent card)

4. All API endpoints remain unchanged:

   • POST / for A2A protocol
   • GET /health for health checks
   • GET /metrics for monitoring
   • GET /agent/skills for capabilities

COMMIT DETAILS

Key Commits:

• 2566b85: Remove docs and favicon endpoints, add tunnel launch comments
• d896cae: Add pragma comments to suppress secret detection warnings
• 855b013: Remove trailing whitespace across codebase

Previous Related Work:

• f17e1ec: Remove frontend integration documentation
• f581ae5: Remove built-in chat UI and static file serving
• c4fda28: Remove Bindu endpoint implementation and A2A protocol adapter

USAGE WITH GIT

Create an annotated tag

git tag -a 2026.7.3 -F release-notes/2026.7.3.txt

Create a GitHub release

gh release create 2026.7.3
--notes-file release-notes/2026.7.3.txt
--title "2026.7.3: UI Separation & Test Fixes"

View this release

git show 2026.7.3

Push tag to remote

git push origin 2026.7.3

2026.6.6: Hydra OAuth2 Migration

Release: Hydra OAuth2 Migration & Dependency Standardization

Version: 2026.6.6 (Commit: c80026c)
Date: February 7, 2026
Author: Raahul Dutta

OVERVIEW

Major refactoring release: Standardizes authentication on Ory Hydra OAuth2,
removes legacy providers (Auth0, Cognito, Kratos), implements hybrid OAuth2 + DID
authentication, and pins all dependency versions for reproducible builds.

BREAKING CHANGES

⚠️ Auth0 and Cognito providers removed

• Only Hydra is now supported as the authentication provider
• Existing Auth0/Cognito configurations will need to migrate to Hydra

⚠️ OAuth client authentication method changed

• Changed from client_secret_basic to client_secret_post
• DIDs containing colons are now properly supported as client_ids

⚠️ Removed modules

• bindu/utils/auth_utils.py (Auth0 JWT utilities)
• bindu/server/middleware/auth/auth0.py
• bindu/server/middleware/auth/cognito.py
• Kratos, Vault, and user OAuth management modules

NEW FEATURES

🔐 Hybrid OAuth2 + DID Authentication

• Combines OAuth2 tokens with DID-based signatures
• DID used as stable key for credential storage
• Automatic client registration in Hydra with DID as client_id
• Public key metadata stored in Hydra client for verification

🔑 Improved Hydra Client Registration

• Verifies client exists in Hydra before returning cached credentials
• Automatically recreates client if local credentials are stale
• Uses client_secret_post for token endpoint authentication
• Proper URL encoding for DIDs with special characters

📦 Pinned Dependency Versions

• All dependencies now use exact versions (==) instead of minimum (>=)
• Prevents unexpected breakages from upstream updates
• Dependencies organized into functional groups:
  • Core runtime (15 packages)
  • Telemetry (7 packages)
  • Payments/x402 (5 packages)
  • Storage (4 packages)
  • CLI tools (2 packages)
  • Security (1 package)

🖥️ New Web UI Infrastructure

• Static file serving for agent web interface
• Modular JavaScript architecture:
  • api/client.js - HTTP client utilities
  • state/store.js - State management
  • chat/chat.js - Chat functionality
  • core/ - Protocol, events, constants

💬 Startup Display Improvements

• OAuth token retrieval curl command shown at startup
• Client secret path displayed (not exposed directly)
• Clear instructions for obtaining access tokens

IMPROVEMENTS

🏗️ Authentication Architecture

• Single auth provider (Hydra) simplifies configuration
• HydraMiddleware handles OAuth2 token introspection
• DID signature verification for enhanced security
• Cleaner separation between auth and middleware layers

📝 Configuration Validation

• Simplified config validator for Hydra-only setup
• Removed Auth0/Cognito validation logic
• Better error messages for invalid configurations

🧪 Test Simplification

• Removed complex mocking in auth tests
• Simplified hybrid auth client tests
• Removed outdated registration tests
• 565 tests passing with 68.59% coverage

📚 Documentation Updates

• examples/README.md updated for Hydra-only setup
• Removed Auth0 token retrieval examples
• Added Hydra token retrieval instructions

TECHNICAL DETAILS

Files Changed: 60+ files

• Added: 25+ files (Hydra client, registration, middleware, UI)
• Modified: 20+ files (settings, config, applications)
• Deleted: 15+ files (Auth0, Cognito, Kratos, Vault modules)

New Modules:

• bindu/auth/hydra/client.py (272 lines) - Hydra Admin API client
• bindu/auth/hydra/registration.py (220 lines) - Agent registration
• bindu/server/middleware/auth/hydra.py (397 lines) - OAuth2 middleware
• bindu/utils/agent_token_utils.py (178 lines) - Token utilities
• bindu/utils/did_signature.py (234 lines) - DID signature utilities
• bindu/ui/static/ - Web UI static files

Removed Modules:

• bindu/utils/auth_utils.py - Auth0 JWT utilities
• bindu/server/middleware/auth/auth0.py - Auth0 middleware
• bindu/server/middleware/auth/cognito.py - Cognito middleware
• Kratos configuration and migration scripts

DEPENDENCY CHANGES

Core Dependencies (pinned versions):

• uvicorn==0.34.1
• starlette==0.48.0
• pydantic==2.11.3
• loguru==0.7.3
• rich==13.9.4
• cryptography==44.0.2
• httpx==0.28.1
• pyjwt[crypto]==2.10.1

Removed Dependencies:

• openai, agno, ddgs (AI/search - not needed)
• numpy (heavy - not needed)
• ty (dev tool - moved to dev deps)

TESTING

✅ 565 tests passing
✅ Coverage: 68.59%
✅ All Hydra authentication flows tested
✅ DID signature verification tested
✅ Token introspection and refresh tested

MIGRATION GUIDE

For existing Auth0 deployments:

1. Set up Ory Hydra server (or use https://hydra.getbindu.com)

2. Update environment variables:

   Remove

   AUTH0_DOMAIN=...
   AUTH0_AUDIENCE=...
   AUTH0_CLIENT_ID=...
   AUTH0_CLIENT_SECRET=...

   Add

   HYDRA__ADMIN_URL=https://hydra-admin.getbindu.com
   HYDRA__PUBLIC_URL=https://hydra.getbindu.com
   AUTH__ENABLED=true
   AUTH__PROVIDER=hydra

3. Update agent config:
   auth:
   enabled: true
   provider: hydra # Only option now

4. Agent will auto-register in Hydra on startup with DID as client_id

5. Get token using:
   curl 'https://hydra.getbindu.com/oauth2/token'
   -d 'grant_type=client_credentials'
   -d 'client_id=YOUR_DID'
   -d 'client_secret=YOUR_SECRET'

For Cognito deployments:

• Full migration to Hydra required
• No direct migration path available

COMMIT DETAILS

Merge Commit: c80026c
PR: #135 (Feature/hydra migration v2)
Branch: feature/hydra-migration-v2
Commits: 36

Key Commits:

• add4d56: Remove Auth0/Cognito, standardize on Hydra
• 2108e97: Pin all dependency versions
• 4da6c58: Improve Hydra registration, switch to client_secret_post
• 979d836: Implement hybrid OAuth2 + DID authentication
• 31f4388: Remove Kratos, OAuth, Vault modules
• 93c92ec: Use DID as stable key for credential storage

USAGE WITH GIT

Create an annotated tag

git tag -a 2026.6.6 c80026c -F release-notes/2026.6.6.txt

Create a GitHub release

gh release create 2026.6.6
--notes-file release-notes/2026.6.6.txt
--title "2026.6.6: Hydra OAuth2 Migration"

View this release

git show 2026.6.6

Push tag to remote

git push origin 2026.6.6