Extract _get_api_key() and _create_provider_instance() as a single internal
factory that handles all provider types, including MOCK. Both create_llm() and
create_ai_provider() now delegate to _create_provider_instance(), eliminating
the duplicated if/elif provider-switching chains and the divergence between the
two code paths. Adding a new provider now requires touching exactly one place.
Key changes:
- New _get_api_key(provider_type) consolidates API key lookup and validation
that was previously duplicated across create_llm(), _create_provider_llm(),
and every branch of create_ai_provider().
- New _create_provider_instance() is the unified raw-LLM factory, replacing
_create_provider_llm() and the specialised adapter constructors in
create_ai_provider(). MOCK is now handled here via FakeListLLM.
- create_ai_provider() wraps all providers uniformly in LangChainChatProvider
instead of using specialised adapters (OpenAIChatProvider, AnthropicChatProvider,
GoogleChatProvider, OpenRouterChatProvider) for the four primary providers.
- create_llm() drops its own API key validation block; validation now happens
inside _create_provider_instance() via _get_api_key().
- All BDD scenarios updated: _create_provider_llm references become
_create_provider_instance, and provider-type assertions on create_ai_provider
results are updated to LangChainChatProvider.
Review fixes (Cycle 2):
- Add _coerce_env_bool() for consistent boolean env-var coercion in
CLEVERAGENTS_ALLOW_MOCK_PROVIDER checks.
- Introduce _ApiKeyMissing sentinel to distinguish 'not provided' from None
in provider configuration.
- Set MOCK supports_streaming=False in DEFAULT_CAPABILITIES to align with
FakeListLLM semantics.
- Make MOCK is_configured conditional on CLEVERAGENTS_ALLOW_MOCK_PROVIDER.
- Use FakeListLLM(responses=['mock response'] * 10) to prevent IndexError
in multi-step workflows.
- Strip max_retries from kwargs before passing to LangChain constructors.
- Extract _resolve_provider_type() helper shared by create_llm() and
create_ai_provider() to reduce duplication and improve readability.
- Ensure __api_key_sentinel flows through factory_kwargs even when api_key
is None, avoiding double _get_api_key() calls.
- Add CHANGELOG env-var documentation and providers.md env-var table.
- Resolve template DB lock issues by persisting in-memory SQLite via
VACUUM INTO instead of direct file creation on tmpfs.
ISSUES CLOSED: #10949
- docs/api/actor.md: Add InvariantReconciliationActor section documenting
the built-in reconciliation actor introduced in v3.8.0, including the
reconciliation algorithm, ReconciliationResult/ConflictRecord/ScopeInvariants
data classes, standalone reconcile_invariants() function, DI registration,
and failure behaviour.
- docs/modules/devcontainer-discovery.md: New module guide for the
devcontainer auto-discovery system (v3.8.0 fix#2615), covering
DevcontainerDiscoveryResult, discover_devcontainers(), is_trigger_type(),
monorepo named-config support, and gotchas.
- mkdocs.yml: Add 'Devcontainer Auto-Discovery' to the Modules nav section,
alongside shell-safety, uko-provenance, invariant-reconciliation,
context-hydration, and git-worktree-sandbox module docs.
- robot/coverage_threshold.robot: Add tdd_issue and tdd_issue_4305 tags
to the Noxfile Contains Coverage Threshold Constant test case.
ISSUES CLOSED: #4485
- Add docs/api/action.md: full API reference for ActionConfigSchema and ActionArgumentSchema — field tables, factory methods, camelCase compat mapping, env-var interpolation, database integrity note, and complete YAML example
- Update docs/api/index.md: add cleveragents.action entry to module index
- Update mkdocs.yml: add 'Action Schema: api/action.md' to the API Reference nav
- Update CHANGELOG.md [Unreleased] Fixed: document plan use UNIQUE constraint violation fix (#4174, #4197)
- Clarify from_yaml_file ValueError semantics, document inputs_schema type as dict[str, Any] | None, and update A2A ASV benchmarks to pass method= requests after JSON-RPC migration
ISSUES CLOSED: #7472
Add comprehensive API documentation for the cleveragents.acms package,
covering the four-layer UKO ontology hierarchy (Layer 0-3), all public
types (VocabularyRegistry, ProvenanceInfo, UKOClass, UKOProperty,
UKOVocabulary, Layer2Dependency, ParadigmVocabulary), detail level maps
(DetailLevelMapBuilder, build_detail_level_map, build_effective_map,
resolve_detail_level), and all Layer 3 language vocabulary types for
Python, TypeScript, Rust, and Java.
- Add docs/api/acms.md with full API reference and usage example
- Update docs/api/index.md to include ACMS/UKO in the module index
- Update mkdocs.yml nav to include the new ACMS/UKO page
- Update CHANGELOG.md [Unreleased] with the documentation addition
Add cleveragents.providers to the API Reference module index table.
The providers.md page already exists but was missing from the index,
making it undiscoverable via the documentation navigation.
ISSUES CLOSED: #4940
- docs/api/tui.md: Document ShellDangerLevel, DangerousPattern, DEFAULT_PATTERNS,
DangerousPatternDetector, ShellSafetyService, and SafetyCheckResult with
full API reference, parameter tables, and usage examples
- docs/architecture.md: Add Invariant Reconciliation section covering the
builtin/invariant-reconciliation actor, four-scope algorithm, failure
behaviour, and DI registration
- README.md: Add Invariant Reconciliation, TUI shell danger detection, and
UKO provenance tracking to the Highlights section
ISSUES CLOSED: #3377
- Promote [Unreleased] CHANGELOG entries to [3.8.0] (2026-04-05)
- Add Shell Danger Detection section to docs/api/tui.md covering
ShellDangerLevel, DangerousPattern, ShellSafetyService, and
SafetyCheckResult with full API reference and usage examples
- Add InvariantService section to docs/api/core.md documenting
the new DI-registered singleton, its methods, and emitted events
- Update docs/architecture.md Plan Lifecycle section to document
invariant reconciliation as a phase transition gate
- Update README.md Highlights with shell danger detection, inline
permission questions, invariant reconciliation, UKO provenance
tracking, and JSON-RPC 2.0 A2A wire format
- Create docs/modules/shell-safety.md with full module guide
covering purpose, key classes, built-in patterns, custom pattern
registration, TUI integration, and testing guidance
ISSUES CLOSED: #1003#997#1391#1004#891#1501#1577#1941#2334
- docs/api/providers.md: new comprehensive API reference for
cleveragents.providers — ProviderRegistry, ProviderType,
ProviderCapabilities, ProviderInfo, LangChainChatProvider,
module-level helpers, environment variables, and ASV benchmarks
- docs/api/index.md: add providers module to module index table
- docs/architecture.md: add Provider Registry section with discovery,
selection, and factory usage examples
- CHANGELOG.md: add [Unreleased] entries for:
- agents plan list --namespace/-n option (#2616)
- ASV benchmark suite for providers module (#3022)
- MCP error extraction from content[0].text per MCP 1.4.0 (#2600)
- CI quality gates restored to passing on master (#2629)
Add DomainBaseModel section to docs/api/core.md documenting the shared Pydantic base class from PR #2014 (issue #1941), and add CHANGELOG entry for the CI template DB extension from PR #2399 (issue #2334).
ISSUES CLOSED: #1941
Co-authored-by: Jeffrey Phillips Freeman <jeffrey.freeman@cleverthis.com>
Co-committed-by: Jeffrey Phillips Freeman <jeffrey.freeman@cleverthis.com>
Add PermissionQuestionWidget API documentation to docs/api/tui.md including
method table, key bindings, PermissionDecisionEvent dataclass, and
render_permission_question() helper reference. Add corresponding CHANGELOG
entry under [Unreleased] Added section.
Refs: #997
- CHANGELOG: add [Unreleased] entries for TUI first-run experience (#1391),
session Markdown export (#1004), and UKO provenance/temporal versioning (#891)
- README: add first-run experience and Markdown transcript export bullets
- docs/api/tui.md: new TUI API reference covering first-run, persona system,
input routing, slash commands, session export/import, and widgets
- docs/api/index.md: add TUI entry to module index
- docs/api/resource.md: document DatabaseResourceHandler and DevcontainerHandler
full protocol implementations with method tables and examples
- docs/architecture.md: expand UKO section with provenance/temporal versioning
details; update TUI design decision summary
- mkdocs.yml: add TUI page to API Reference nav
ISSUES CLOSED: #1391#1004#891
Add docs/api/ with per-module API documentation for core, a2a, actor,
skills, tool, mcp, resource, and config packages. Add docs/architecture.md
with a developer-oriented system overview including component map, layer
diagram, plan lifecycle, and key design decisions. Update mkdocs.yml nav
to expose both new sections.
ISSUES CLOSED: #N/A
hurui200320
HAL9000
HAL9000
freemo