chore: release v0.3.0 with v2 prompts and fixes

- Fix Black formatting issues for CI/CD compliance
- Add experimental v2 prompts with confidence scoring
- Include comprehensive documentation and examples
- Update version to 0.3.0 for PyPI release

Author: User

.gitignore

@@ -70,6 +70,7 @@ venv.bak/
 # Project specific
 *.pdf
 ACE_IMPROVEMENTS.md
+ACE_ROADMAP.md
 *.egg-info/
 reports/
 docs/method_outline.md

CHANGELOG.md

@@ -5,17 +5,33 @@ All notable changes to ACE Framework will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.3.0] - 2025-10-16
 
 ### Added
+- **Experimental v2 Prompts** with state-of-the-art prompt engineering
+  - Confidence scoring at bullet and answer levels
+  - Domain-specific variants for math and code generation
+  - Hierarchical structure with identity headers and metadata
+  - Concrete examples and anti-patterns for better guidance
+  - PromptManager for version control and A/B testing
+- Comprehensive prompt engineering documentation (`docs/PROMPT_ENGINEERING.md`)
+- Advanced examples demonstrating v2 prompts (`examples/advanced_prompts_v2.py`)
+- Comparison script for v1 vs v2 prompts (`examples/compare_v1_v2_prompts.py`)
 - Playbook persistence with `save_to_file()` and `load_from_file()` methods
 - Example demonstrating playbook save/load functionality (`examples/playbook_persistence.py`)
 - py.typed file for PEP 561 type hint support
-- Documentation for playbook persistence in README
+- Mermaid flowchart visualization in README showing ACE learning loop
+- ACE_ROADMAP.md (untracked) for development planning
+
+### Changed
+- Enhanced docstrings with comprehensive examples throughout codebase
+- Improved README with v2 prompts section and visual diagrams
+- Updated formatting to comply with Black code style
 
 ### Fixed
 - README incorrectly referenced non-existent docs/ directory
 - Test badge URL in README (test.yml → tests.yml)
+- Code formatting issues detected by GitHub Actions
 
 ## [0.2.0] - 2025-10-15
 

ace/__init__.py

@@ -23,6 +23,7 @@
 # Import production LLM clients if available
 try:
     from .llm_providers import LiteLLMClient
+
     LITELLM_AVAILABLE = True
 except ImportError:
     LiteLLMClient = None

ace/adaptation.py

@@ -8,7 +8,14 @@
 from typing import Dict, Iterable, List, Optional, Sequence
 
 from .playbook import Playbook
-from .roles import Curator, CuratorOutput, Generator, GeneratorOutput, Reflector, ReflectorOutput
+from .roles import (
+    Curator,
+    CuratorOutput,
+    Generator,
+    GeneratorOutput,
+    Reflector,
+    ReflectorOutput,
+)
 
 
 @dataclass
@@ -116,7 +123,9 @@ def _update_recent_reflections(self, reflection: ReflectorOutput) -> None:
         serialized = json.dumps(reflection.raw, ensure_ascii=False)
         self._recent_reflections.append(serialized)
         if len(self._recent_reflections) > self.reflection_window:
-            self._recent_reflections = self._recent_reflections[-self.reflection_window :]
+            self._recent_reflections = self._recent_reflections[
+                -self.reflection_window :
+            ]
 
     def _apply_bullet_tags(self, reflection: ReflectorOutput) -> None:
         for tag in reflection.bullet_tags:
@@ -125,7 +134,9 @@ def _apply_bullet_tags(self, reflection: ReflectorOutput) -> None:
             except ValueError:
                 continue
 
-    def _question_context(self, sample: Sample, environment_result: EnvironmentResult) -> str:
+    def _question_context(
+        self, sample: Sample, environment_result: EnvironmentResult
+    ) -> str:
         parts = [
             f"question: {sample.question}",
             f"context: {sample.context}",
@@ -135,7 +146,9 @@ def _question_context(self, sample: Sample, environment_result: EnvironmentResul
         ]
         return "\n".join(parts)
 
-    def _progress_string(self, epoch: int, total_epochs: int, step: int, total_steps: int) -> str:
+    def _progress_string(
+        self, epoch: int, total_epochs: int, step: int, total_steps: int
+    ) -> str:
         return f"epoch {epoch}/{total_epochs} · sample {step}/{total_steps}"
 
     def _process_sample(
@@ -169,7 +182,9 @@ def _process_sample(
             reflection=reflection,
             playbook=self.playbook,
             question_context=self._question_context(sample, env_result),
-            progress=self._progress_string(epoch, total_epochs, step_index, total_steps),
+            progress=self._progress_string(
+                epoch, total_epochs, step_index, total_steps
+            ),
         )
         self.playbook.apply_delta(curator_output.delta)
         return AdapterStepResult(

ace/llm.py

@@ -134,7 +134,9 @@ def _extract_text(self, outputs: Any) -> str:
             return str(generated)
 
         # Older versions might return {"generated_text": "..."}
-        if isinstance(candidate, dict) and isinstance(candidate.get("generated_text"), str):
+        if isinstance(candidate, dict) and isinstance(
+            candidate.get("generated_text"), str
+        ):
             return candidate["generated_text"].strip()
 
         # Ultimate fallback: string representation.

ace/llm_providers/__init__.py

@@ -10,4 +10,4 @@
 __all__ = [
     "LiteLLMClient",
     "LangChainLiteLLMClient",
-]
+]

ace/llm_providers/langchain_client.py

@@ -6,6 +6,7 @@
 try:
     from langchain_litellm import ChatLiteLLM, ChatLiteLLMRouter
     from litellm import Router
+
     LANGCHAIN_AVAILABLE = True
 except ImportError:
     LANGCHAIN_AVAILABLE = False
@@ -59,7 +60,7 @@ def __init__(
         router: Optional[Any] = None,  # Router from litellm
         temperature: float = 0.0,
         max_tokens: Optional[int] = None,
-        **kwargs
+        **kwargs,
     ):
         if not LANGCHAIN_AVAILABLE:
             raise ImportError(
@@ -74,28 +75,27 @@ def __init__(
 
         # Initialize the appropriate LangChain client
         if router:
-            logger.info(f"Initializing LangChainLiteLLMClient with router for model: {model}")
+            logger.info(
+                f"Initializing LangChainLiteLLMClient with router for model: {model}"
+            )
             self.llm = ChatLiteLLMRouter(
                 router=router,
                 model_name=model,
                 temperature=temperature,
                 max_tokens=max_tokens,
-                **kwargs
+                **kwargs,
             )
             self.is_router = True
         else:
             logger.info(f"Initializing LangChainLiteLLMClient for model: {model}")
             self.llm = ChatLiteLLM(
-                model=model,
-                temperature=temperature,
-                max_tokens=max_tokens,
-                **kwargs
+                model=model, temperature=temperature, max_tokens=max_tokens, **kwargs
             )
             self.is_router = False
 
     def _filter_kwargs(self, kwargs: Dict[str, Any]) -> Dict[str, Any]:
         """Filter out ACE-specific parameters that shouldn't go to LangChain."""
-        ace_specific_params = {'refinement_round', 'max_refinement_rounds'}
+        ace_specific_params = {"refinement_round", "max_refinement_rounds"}
         return {k: v for k, v in kwargs.items() if k not in ace_specific_params}
 
     def complete(self, prompt: str, **kwargs) -> LLMResponse:
@@ -121,7 +121,7 @@ def complete(self, prompt: str, **kwargs) -> LLMResponse:
             }
 
             # Add usage information if available
-            if hasattr(response, 'usage_metadata') and response.usage_metadata:
+            if hasattr(response, "usage_metadata") and response.usage_metadata:
                 metadata["usage"] = {
                     "prompt_tokens": response.usage_metadata.get("input_tokens"),
                     "completion_tokens": response.usage_metadata.get("output_tokens"),
@@ -131,12 +131,11 @@ def complete(self, prompt: str, **kwargs) -> LLMResponse:
             # Add router information if using router
             if self.is_router:
                 metadata["router"] = True
-                metadata["model_used"] = response.response_metadata.get("model_name", self.model)
+                metadata["model_used"] = response.response_metadata.get(
+                    "model_name", self.model
+                )
 
-            return LLMResponse(
-                text=response.content,
-                raw=metadata
-            )
+            return LLMResponse(text=response.content, raw=metadata)
 
         except Exception as e:
             logger.error(f"Error in LangChain completion: {e}")
@@ -165,7 +164,7 @@ async def acomplete(self, prompt: str, **kwargs) -> LLMResponse:
             }
 
             # Add usage information if available
-            if hasattr(response, 'usage_metadata') and response.usage_metadata:
+            if hasattr(response, "usage_metadata") and response.usage_metadata:
                 metadata["usage"] = {
                     "prompt_tokens": response.usage_metadata.get("input_tokens"),
                     "completion_tokens": response.usage_metadata.get("output_tokens"),
@@ -175,12 +174,11 @@ async def acomplete(self, prompt: str, **kwargs) -> LLMResponse:
             # Add router information if using router
             if self.is_router:
                 metadata["router"] = True
-                metadata["model_used"] = response.response_metadata.get("model_name", self.model)
+                metadata["model_used"] = response.response_metadata.get(
+                    "model_name", self.model
+                )
 
-            return LLMResponse(
-                text=response.content,
-                raw=metadata
-            )
+            return LLMResponse(text=response.content, raw=metadata)
 
         except Exception as e:
             logger.error(f"Error in async LangChain completion: {e}")
@@ -201,7 +199,7 @@ def complete_with_stream(self, prompt: str, **kwargs) -> Iterator[str]:
 
         try:
             for chunk in self.llm.stream(prompt, **filtered_kwargs):
-                if hasattr(chunk, 'content') and chunk.content:
+                if hasattr(chunk, "content") and chunk.content:
                     yield chunk.content
         except Exception as e:
             logger.error(f"Error in LangChain streaming: {e}")
@@ -222,8 +220,8 @@ async def acomplete_with_stream(self, prompt: str, **kwargs) -> AsyncIterator[st
 
         try:
             async for chunk in self.llm.astream(prompt, **filtered_kwargs):
-                if hasattr(chunk, 'content') and chunk.content:
+                if hasattr(chunk, "content") and chunk.content:
                     yield chunk.content
         except Exception as e:
             logger.error(f"Error in async LangChain streaming: {e}")
-            raise
+            raise