Merge pull request #84 from kayba-ai/cleanup

Clean up imports and remove unused exports from ace and ace_next

Author: Lanzelot1

AGENTS.md

@@ -14,8 +14,8 @@ When changes to code alter architecture, add new modules, change public APIs, re
 
 ### Project Structure
 - `ace/` — core library (skillbook, roles, adapters, integrations, observability)
-- `ace_next/` — pipeline-based rewrite (see `docs/ACE_DESIGN.md`)
-- `pipeline/` — generic pipeline engine (see `docs/PIPELINE_DESIGN.md`)
+- `ace_next/` — pipeline-based rewrite built on top of `pipeline/` (see `docs/ACE_DESIGN.md`)
+- `pipeline/` — generic pipeline engine that `ace_next` is built on (see `docs/PIPELINE_DESIGN.md`)
 - `tests/` — unit/integration tests (pytest + unittest)
 - `examples/` — runnable demos grouped by integration
 - `benchmarks/`, `scripts/` — research/evaluation tooling (not shipped to PyPI)

README.md

@@ -14,6 +14,8 @@
 
 ⭐ Star this repo if you find it useful!
 
+> **🚀 ACE v2 is coming.** We're rebuilding the framework from the ground up — a cleaner architecture, a modular pipeline engine, first-class async support, and a dramatically simpler API. Everything you love about ACE, refined and supercharged. Follow the progress in [`ace_next/`](ace_next/) and [`pipeline/`](pipeline/), or join the [Discord](https://discord.gg/mqCqH7sTyK) to stay in the loop.
+
 ---
 
 ## What is ACE?
@@ -182,16 +184,14 @@ flowchart LR
 
 ## Documentation
 
-- [Quick Start Guide](docs/QUICK_START.md) - Get running in 5 minutes
-- [Setup Guide](docs/SETUP_GUIDE.md) - Installation, configuration, providers
-- [Integration Guide](docs/INTEGRATION_GUIDE.md) - Add ACE to existing agents
-- [API Reference](docs/API_REFERENCE.md) - Complete API documentation
-- [Complete Guide to ACE](docs/COMPLETE_GUIDE_TO_ACE.md) - Deep dive into concepts
-- [Prompt Engineering](docs/PROMPT_ENGINEERING.md) - Advanced prompt techniques
-- [Insight Source Tracing](docs/INSIGHT_SOURCES.md) - Track skill provenance and query origins
-- [Agentic System Prompting](examples/agentic-system-prompting/README.md) - Automatically generate prompt improvements from past traces
+**📖 [docs.kayba.ai](https://kayba-ai.github.io/agentic-context-engine/latest/)** — Full documentation with guides, API reference, and examples.
+
+Quick links:
+- [Quick Start Guide](https://kayba-ai.github.io/agentic-context-engine/latest/getting-started/quickstart/) - Get running in 5 minutes
+- [Setup Guide](https://kayba-ai.github.io/agentic-context-engine/latest/getting-started/setup/) - Installation, configuration, providers
+- [Integration Guide](https://kayba-ai.github.io/agentic-context-engine/latest/integrations/browser-use/) - Add ACE to existing agents
+- [API Reference](https://kayba-ai.github.io/agentic-context-engine/latest/api/) - Complete API documentation
 - [Examples](examples/) - Ready-to-run code examples
-- [Benchmarks](benchmarks/README.md) - Evaluate ACE performance
 - [Changelog](CHANGELOG.md) - Recent changes
 
 ---

ace/__init__.py

@@ -3,7 +3,7 @@
 from typing import Optional
 from .skillbook import Skill, Skillbook
 from .updates import UpdateOperation, UpdateBatch
-from .llm import LLMClient, DummyLLMClient, TransformersLLMClient
+from .llm import LLMClient, DummyLLMClient
 from .roles import (
     Agent,
     ReplayAgent,
@@ -22,121 +22,56 @@
     TaskEnvironment,
     SimpleEnvironment,
     EnvironmentResult,
-    ACEStepResult,
-)
-from .async_learning import (
-    LearningTask,
-    ReflectionResult,
-    ThreadSafeSkillbook,
-    AsyncLearningPipeline,
 )
+from .deduplication import DeduplicationConfig
 
 # Import optional feature detection
-from .features import has_opik, has_litellm
-
-# Import observability components if available
-if has_opik():
-    try:
-        from .observability import OpikIntegration as _OpikIntegration
-
-        OpikIntegration: Optional[type] = _OpikIntegration
-        OBSERVABILITY_AVAILABLE = True
-    except ImportError:
-        OpikIntegration: Optional[type] = None  # type: ignore
-        OBSERVABILITY_AVAILABLE = False
-else:
-    OpikIntegration: Optional[type] = None  # type: ignore
-    OBSERVABILITY_AVAILABLE = False
+from .features import has_litellm
 
-# Import production LLM clients if available
+# Import production LLM client if available
 if has_litellm():
     try:
         from .llm_providers import LiteLLMClient as _LiteLLMClient
 
         LiteLLMClient: Optional[type] = _LiteLLMClient
-        LITELLM_AVAILABLE = True
     except ImportError:
         LiteLLMClient: Optional[type] = None  # type: ignore
-        LITELLM_AVAILABLE = False
 else:
     LiteLLMClient: Optional[type] = None  # type: ignore
-    LITELLM_AVAILABLE = False
 
-# Import Claude Code CLI LLM client (uses subscription auth, no API key needed)
-try:
-    from .llm_providers import (
-        ClaudeCodeLLMClient as _ClaudeCodeLLMClient,
-        CLAUDE_CODE_CLI_AVAILABLE as _CLAUDE_CODE_CLI_AVAILABLE,
-    )
-
-    ClaudeCodeLLMClient: Optional[type] = _ClaudeCodeLLMClient
-    CLAUDE_CODE_CLI_AVAILABLE = _CLAUDE_CODE_CLI_AVAILABLE
-except ImportError:
-    ClaudeCodeLLMClient: Optional[type] = None  # type: ignore
-    CLAUDE_CODE_CLI_AVAILABLE = False
-
-# Import integrations (LiteLLM, browser-use, LangChain, Claude Code, etc.) if available
+# Import integrations if available
 try:
     from .integrations import (
         ACELiteLLM as _ACELiteLLM,
         ACEAgent as _ACEAgent,
         ACELangChain as _ACELangChain,
         ACEClaudeCode as _ACEClaudeCode,
         wrap_skillbook_context as _wrap_skillbook_context,
-        BROWSER_USE_AVAILABLE as _BROWSER_USE_AVAILABLE,
-        LANGCHAIN_AVAILABLE as _LANGCHAIN_AVAILABLE,
-        CLAUDE_CODE_AVAILABLE as _CLAUDE_CODE_AVAILABLE,
     )
 
     ACELiteLLM: Optional[type] = _ACELiteLLM
     ACEAgent: Optional[type] = _ACEAgent
     ACELangChain: Optional[type] = _ACELangChain
     ACEClaudeCode: Optional[type] = _ACEClaudeCode
     wrap_skillbook_context: Optional[type] = _wrap_skillbook_context  # type: ignore
-    BROWSER_USE_AVAILABLE = _BROWSER_USE_AVAILABLE
-    LANGCHAIN_AVAILABLE = _LANGCHAIN_AVAILABLE
-    CLAUDE_CODE_AVAILABLE = _CLAUDE_CODE_AVAILABLE
 except ImportError:
     ACELiteLLM: Optional[type] = None  # type: ignore
     ACEAgent: Optional[type] = None  # type: ignore
     ACELangChain: Optional[type] = None  # type: ignore
     ACEClaudeCode: Optional[type] = None  # type: ignore
     wrap_skillbook_context: Optional[type] = None  # type: ignore
-    BROWSER_USE_AVAILABLE = False
-    LANGCHAIN_AVAILABLE = False
-    CLAUDE_CODE_AVAILABLE = False
-
-# Import deduplication module
-from .deduplication import (
-    DeduplicationConfig,
-    DeduplicationManager,
-)
-
-# Import recursive reflector module
-from .reflector import (
-    RecursiveConfig,
-    RecursiveReflector,
-    TraceSandbox,
-    TraceContext,
-)
-
-# Import insight source tracing
-from .insight_source import InsightSource, TraceReference
-
-# Import unified PromptManager
-from .prompt_manager import PromptManager
 
 __all__ = [
-    # Core components
+    # Core data types
     "Skill",
     "Skillbook",
     "UpdateOperation",
     "UpdateBatch",
+    # LLM clients
     "LLMClient",
     "DummyLLMClient",
-    "TransformersLLMClient",
     "LiteLLMClient",
-    "ClaudeCodeLLMClient",  # Claude Code CLI client (subscription auth)
+    # Roles
     "Agent",
     "ReplayAgent",
     "Reflector",
@@ -145,45 +80,21 @@
     "AgentOutput",
     "ReflectorOutput",
     "SkillManagerOutput",
+    # Adaptation loops
+    "ACEBase",
     "OfflineACE",
     "OnlineACE",
-    "ACEBase",
     "Sample",
     "TaskEnvironment",
     "SimpleEnvironment",
     "EnvironmentResult",
-    "ACEStepResult",
-    # Deduplication
+    # Integrations
+    "ACELiteLLM",
+    "ACEAgent",
+    "ACELangChain",
+    "ACEClaudeCode",
+    # Configuration
     "DeduplicationConfig",
-    "DeduplicationManager",
-    # Recursive reflector
-    "RecursiveConfig",
-    "RecursiveReflector",
-    "TraceSandbox",
-    "TraceContext",
-    # Out-of-box integrations
-    "ACELiteLLM",  # LiteLLM integration (quick start)
-    "ACEAgent",  # Browser-use integration
-    "ACELangChain",  # LangChain integration (complex workflows)
-    "ACEClaudeCode",  # Claude Code CLI integration
     # Utilities
     "wrap_skillbook_context",
-    # Async learning
-    "LearningTask",
-    "ReflectionResult",
-    "ThreadSafeSkillbook",
-    "AsyncLearningPipeline",
-    # Feature flags
-    "OpikIntegration",
-    "LITELLM_AVAILABLE",
-    "CLAUDE_CODE_CLI_AVAILABLE",  # Claude Code CLI available
-    "OBSERVABILITY_AVAILABLE",
-    "BROWSER_USE_AVAILABLE",
-    "LANGCHAIN_AVAILABLE",
-    "CLAUDE_CODE_AVAILABLE",
-    # Insight source tracing
-    "InsightSource",
-    "TraceReference",
-    # Prompt management
-    "PromptManager",
 ]

ace/integrations/claude_code/learner.py

@@ -33,21 +33,41 @@
 from pathlib import Path
 from typing import List, Optional, Any
 
-from dotenv import load_dotenv
-from tenacity import (
-    retry,
-    stop_after_attempt,
-    wait_exponential,
-)
+try:
+    from dotenv import load_dotenv
+except ImportError:
+    load_dotenv = None  # type: ignore[assignment]
+
+try:
+    from tenacity import (
+        retry,
+        stop_after_attempt,
+        wait_exponential,
+    )
+except ImportError:
+    # Fallback: no-op retry decorator when tenacity is not installed
+    def retry(**kwargs):  # type: ignore[misc]
+        def decorator(func):
+            return func
+
+        return decorator
+
+    def stop_after_attempt(n):  # type: ignore[misc]
+        return n
+
+    def wait_exponential(**kwargs):  # type: ignore[misc]
+        return None
+
 
 # Load .env file from ~/.ace/.env or current directory
-_env_paths = [
-    Path.home() / ".ace" / ".env",
-    Path.cwd() / ".env",
-]
-for _env_path in _env_paths:
-    if _env_path.exists():
-        load_dotenv(_env_path)
+if load_dotenv is not None:
+    _env_paths = [
+        Path.home() / ".ace" / ".env",
+        Path.cwd() / ".env",
+    ]
+    for _env_path in _env_paths:
+        if _env_path.exists():
+            load_dotenv(_env_path)
         break
 
 from ...skillbook import Skillbook

ace/llm_providers/instructor_client.py

@@ -12,10 +12,15 @@
 
 logger = logging.getLogger(__name__)
 
-# Instructor is a core dependency - always available
-import instructor
 from litellm import completion
 
+try:
+    import instructor
+
+    INSTRUCTOR_AVAILABLE = True
+except ImportError:
+    INSTRUCTOR_AVAILABLE = False
+
 T = TypeVar("T", bound=BaseModel)
 
 
@@ -51,7 +56,7 @@ class InstructorClient:
     def __init__(
         self,
         llm: LLMClient,
-        mode=instructor.Mode.MD_JSON,
+        mode=None,
         max_retries: int = 3,
     ):
         """
@@ -63,9 +68,14 @@ def __init__(
                    MD_JSON works with all models including local ones; use Mode.JSON for OpenAI structured outputs
             max_retries: Maximum validation retries
         """
+        if not INSTRUCTOR_AVAILABLE:
+            raise ImportError(
+                "instructor is required for InstructorClient. "
+                "Install it with: pip install ace-framework[instructor]"
+            )
 
         self.llm = llm
-        self.mode = mode
+        self.mode = mode if mode is not None else instructor.Mode.MD_JSON
         self.max_retries = max_retries
 
         # Patch LiteLLM completion function with Instructor
@@ -212,7 +222,7 @@ def complete_structured(
 
 
 def wrap_with_instructor(
-    llm: LLMClient, mode=instructor.Mode.MD_JSON, max_retries: int = 3
+    llm: LLMClient, mode=None, max_retries: int = 3
 ) -> InstructorClient:
     """
     Convenience function to wrap an LLM client with Instructor capabilities.

ace/roles.py

@@ -191,9 +191,15 @@ def __init__(
         if hasattr(llm, "complete_structured"):
             self.llm = llm
         else:
-            from .llm_providers.instructor_client import wrap_with_instructor
+            from .llm_providers.instructor_client import (
+                INSTRUCTOR_AVAILABLE,
+                wrap_with_instructor,
+            )
 
-            self.llm = wrap_with_instructor(llm, max_retries=max_retries)  # type: ignore[assignment]
+            if INSTRUCTOR_AVAILABLE:
+                self.llm = wrap_with_instructor(llm, max_retries=max_retries)  # type: ignore[assignment]
+            else:
+                self.llm = llm
 
         self.prompt_template = prompt_template
         self.max_retries = max_retries
@@ -575,9 +581,15 @@ def __init__(
         if hasattr(llm, "complete_structured"):
             self.llm = llm
         else:
-            from .llm_providers.instructor_client import wrap_with_instructor
+            from .llm_providers.instructor_client import (
+                INSTRUCTOR_AVAILABLE,
+                wrap_with_instructor,
+            )
 
-            self.llm = wrap_with_instructor(llm, max_retries=max_retries)  # type: ignore[assignment]
+            if INSTRUCTOR_AVAILABLE:
+                self.llm = wrap_with_instructor(llm, max_retries=max_retries)  # type: ignore[assignment]
+            else:
+                self.llm = llm
 
         self.prompt_template = prompt_template
         self.mode = mode
@@ -802,9 +814,15 @@ def __init__(
         if hasattr(llm, "complete_structured"):
             self.llm = llm
         else:
-            from .llm_providers.instructor_client import wrap_with_instructor
+            from .llm_providers.instructor_client import (
+                INSTRUCTOR_AVAILABLE,
+                wrap_with_instructor,
+            )
 
-            self.llm = wrap_with_instructor(llm, max_retries=max_retries)  # type: ignore[assignment]
+            if INSTRUCTOR_AVAILABLE:
+                self.llm = wrap_with_instructor(llm, max_retries=max_retries)  # type: ignore[assignment]
+            else:
+                self.llm = llm
 
         self.prompt_template = prompt_template
         self.max_retries = max_retries