FactLite 1.0.0__tar.gz

factlite-1.0.0/FactLite/__init__.py

@@ -0,0 +1,18 @@
+from .core.actions import ReturnBest, RaiseError, ReturnSafeMessage, FallbackAction
+from .core.rules import BaseRule, LLMJudge, CustomJudge
+from .core.verify import verify
+
+# Export components
+class Actions:
+    ReturnBest = ReturnBest
+    RaiseError = RaiseError
+    ReturnSafeMessage = ReturnSafeMessage
+    FallbackAction = FallbackAction
+    
+class rules:
+    BaseRule = BaseRule
+    LLMJudge = LLMJudge
+    CustomJudge = CustomJudge
+
+action = Actions()
+__all__ = ["verify", "rules", "action"]

factlite-1.0.0/FactLite/core/actions.py

@@ -0,0 +1,41 @@
+from abc import ABC, abstractmethod
+import logging
+
+logger = logging.getLogger(__name__)
+
+class FallbackAction(ABC):
+    """Base class for all fallback actions."""
+    @abstractmethod
+    def execute(self, prompt: str, last_answer: str, feedback: str) -> str:
+        """Execute the fallback action.
+        
+        Args:
+            prompt (str): The original user question
+            last_answer (str): The model's last generated answer
+            feedback (str): The feedback from the judge
+            
+        Returns:
+            str: The fallback action's response
+        """
+        pass
+
+class ReturnBest(FallbackAction):
+    """Return the last generated answer despite failing verification."""
+    def execute(self, prompt: str, last_answer: str, feedback: str) -> str:
+        logger.warning("Returning the last generated answer despite failing verification.")
+        return last_answer
+
+class RaiseError(FallbackAction):
+    """Raise an exception if the answer fails verification."""
+    def execute(self, prompt: str, last_answer: str, feedback: str) -> str:
+        logger.error("Raising exception due to factual verification failure.")
+        raise Exception(f"Answer failed factual verification. Last feedback: {feedback}")
+
+class ReturnSafeMessage(FallbackAction):
+    """Return a safe message if the answer fails verification."""
+    def __init__(self, safe_message="抱歉，AI 暂时无法针对该问题给出有确切把握的回答。"):
+        self.safe_message = safe_message
+        
+    def execute(self, prompt: str, last_answer: str, feedback: str) -> str:
+        logger.warning(f"Returning safe message. Original hallucination feedback: {feedback}")
+        return self.safe_message

factlite-1.0.0/FactLite/core/config.py

@@ -0,0 +1,12 @@
+from .actions import ReturnBest, FallbackAction
+from .rules import BaseRule
+
+class Config:
+    def __init__(self, rule: BaseRule = None, 
+                 max_retries: int = 2, 
+                 on_fail: FallbackAction = ReturnBest()):
+        """Initialize the configuration for the FactLite framework"""
+        
+        self.rule = rule
+        self.max_retries = max_retries
+        self.on_fail = on_fail

factlite-1.0.0/FactLite/core/rules.py

@@ -0,0 +1,124 @@
+from abc import ABC, abstractmethod
+import openai
+import json
+import inspect
+
+class BaseRule(ABC):
+    """Base rule class for all judge implementations"""
+    @abstractmethod
+    def evaluate(self, user_prompt, answer):
+        """Evaluate the answer against the user prompt
+        
+        Args:
+            user_prompt (str): The original user question
+            answer (str): The model's answer
+            
+        Returns:
+            dict: A dictionary with "is_pass" (bool) and "feedback" (str) keys
+        """
+        raise NotImplementedError("Subclasses must implement evaluate method")
+
+class LLMJudge(BaseRule):
+    # Note: Assuming the use of the new OpenAI SDK (>=1.0.0)
+    def __init__(self, model="gpt-4o-mini", api_key=None, base_url=None):
+            self.model = model
+            self.base_url = base_url
+            api_key = api_key or openai.api_key
+            self.client = openai.OpenAI(api_key=api_key, base_url=base_url) if hasattr(openai, "OpenAI") else openai
+    
+    def evaluate(self, user_prompt, answer):
+        evaluation_prompt = f"""You are a fact-checking judge. Evaluate the following response to determine if it accurately answers the user's question. Return a JSON object with two fields:
+- is_pass: boolean indicating if the response is factually correct
+- feedback: detailed criticism if is_pass is false, or empty string if true
+
+User question: {user_prompt}
+Response: {answer}
+
+JSON output:"""
+        
+        try:
+            if hasattr(openai, "OpenAI"):
+                response = self.client.chat.completions.create(
+                    model=self.model,
+                    messages=[
+                        {"role": "system", "content": "You are a fact-checking judge. Return only JSON output."},
+                        {"role": "user", "content": evaluation_prompt}
+                    ],
+                    response_format={"type": "json_object"}
+                )
+                result_str = response.choices[0].message.content
+            else:
+                response = self.client.ChatCompletion.create(
+                    model=self.model,
+                    messages=[
+                        {"role": "system", "content": "You are a fact-checking judge. Return only JSON output."},
+                        {"role": "user", "content": evaluation_prompt}
+                    ]
+                )
+                result_str = response.choices[0].message.content
+            
+            return json.loads(result_str)
+        except Exception as e:
+            error_message = f"LLMJudge API call failed: {str(e)}. Please check your API key and network connection."
+            return {
+                "is_pass": False,
+                "feedback": error_message
+            }
+
+class CustomJudge(BaseRule):
+    def __init__(self, eval_func):
+        """Initialize CustomJudge with a custom evaluation function
+        
+        Args:
+            eval_func (callable): A function that takes user_prompt and answer as parameters
+                                    and returns a dict with "is_pass" and "feedback" keys
+        """
+        if not callable(eval_func):
+            raise TypeError("eval_func must be a callable")
+        
+        # Check if the function accepts at least two parameters
+        sig = inspect.signature(eval_func)
+        params = sig.parameters.values()
+        has_var_args = any(p.kind in (p.VAR_POSITIONAL, p.VAR_KEYWORD) for p in params)
+        if not has_var_args and len(params) < 2:
+            raise ValueError("eval_func must accept at least two parameters: user_prompt and answer")
+        
+        self.eval_func = eval_func
+    
+    def evaluate(self, user_prompt, answer):
+        """Evaluate the answer using the custom function with error handling
+        
+        Args:
+            user_prompt (str): The original user question
+            answer (str): The model's answer
+            
+        Returns:
+            dict: A dictionary with "is_pass" (bool) and "feedback" (str) keys
+        """
+        try:
+            # Call the custom evaluation function
+            result = self.eval_func(user_prompt, answer)
+            
+            # Validate the result
+            if not isinstance(result, dict):
+                raise ValueError("eval_func must return a dictionary")
+            
+            if "is_pass" not in result:
+                raise ValueError("Returned dictionary must contain 'is_pass' key")
+            
+            if "feedback" not in result:
+                raise ValueError("Returned dictionary must contain 'feedback' key")
+            
+            if not isinstance(result["is_pass"], bool):
+                raise ValueError("'is_pass' must be a boolean")
+            
+            if not isinstance(result["feedback"], str):
+                raise ValueError("'feedback' must be a string")
+            
+            return result
+        except Exception as e:
+            # Convert any error to a failed evaluation
+            return {
+                "is_pass": False,
+                "feedback": f"Error in custom judge: {str(e)}. Please fix your evaluation function."
+            }

factlite-1.0.0/FactLite/core/verify.py

@@ -0,0 +1,148 @@
+import functools
+import inspect
+import openai
+import logging
+import asyncio
+from .actions import ReturnBest
+from .config import Config
+
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - [FactLite] - %(message)s', datefmt='%H:%M:%S')
+logger = logging.getLogger(__name__)
+
+def _get_prompt_value(user_prompt, args, kwargs):
+    """Get the prompt value from either kwargs or args"""
+    prompt_value = kwargs.get(user_prompt)
+    arg_index = None
+    if not prompt_value and args:
+        prompt_value = args[0]
+        arg_index = 0
+    return prompt_value, arg_index
+
+def _update_prompt(current_prompt, arg_index, args, kwargs, user_prompt):
+    """Update the prompt in either args or kwargs"""
+    new_args = list(args)
+    new_kwargs = kwargs.copy()
+    if arg_index is not None:
+        new_args[arg_index] = current_prompt
+    else:
+        new_kwargs[user_prompt] = current_prompt
+    return new_args, new_kwargs
+
+def _generate_reflection_prompt(prompt_value, best_answer, feedback):
+    """Generate reflection prompt"""
+    return f"""[System Prompt: You need to self-reflect and self-correct]
+Original user question: {prompt_value}
+Your previous answer: {best_answer}
+Judge's feedback: {feedback}
+Please take a deep breath, strictly correct the errors mentioned above, and provide the final perfect answer."""
+
+def verify(user_prompt=None, rule=None, max_retries=2, on_fail=ReturnBest(), config=None):
+    # Handle config parameter
+    if config:
+        max_retries = config.max_retries
+        on_fail = config.on_fail
+        rule = config.rule
+    
+    def decorator(func):
+        # Check if the function is async
+        is_async = inspect.iscoroutinefunction(func)
+        
+        if is_async:
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                prompt_value, arg_index = _get_prompt_value(user_prompt, args, kwargs)
+                
+                retry_count = 0
+                best_answer = None
+                current_prompt = prompt_value
+                
+                while retry_count <= max_retries:
+                    if retry_count == 0:
+                        logger.info("Generating initial answer...")
+                    else:
+                        logger.warning(f"Triggering reflection and rewrite, attempt {retry_count}...")
+                    
+                    new_args, new_kwargs = _update_prompt(current_prompt, arg_index, args, kwargs, user_prompt)
+                    answer = await func(*new_args, **new_kwargs)
+                    best_answer = answer
+                    
+                    logger.info("Evaluating answer quality...")
+                    evaluation_result = await asyncio.to_thread(rule.evaluate, prompt_value, answer)
+                    is_pass = evaluation_result.get("is_pass", False)
+                    feedback = evaluation_result.get("feedback", "")
+                    
+                    if is_pass:
+                        if retry_count > 0:
+                            logger.info("✅ Correction successful, returning the verified answer!")
+                        else:
+                            logger.info("✅ Initial draft is flawless, passing through!")
+                        return answer
+                    
+                    logger.error(f"❌ Hallucination or error detected: {feedback}")
+                    
+                    current_prompt = _generate_reflection_prompt(prompt_value, best_answer, feedback)
+                    retry_count += 1
+                
+                logger.warning("Maximum retries reached, executing fallback strategy.")
+                action_instance = on_fail() if isinstance(on_fail, type) else on_fail
+                if inspect.iscoroutinefunction(action_instance.execute):
+                    return await action_instance.execute(
+                        prompt=prompt_value, 
+                        last_answer=best_answer, 
+                        feedback=feedback
+                    )
+                else:
+                    return action_instance.execute(
+                        prompt=prompt_value, 
+                        last_answer=best_answer, 
+                        feedback=feedback
+                    )
+            return async_wrapper
+        else:
+            @functools.wraps(func)
+            def sync_wrapper(*args, **kwargs):
+                prompt_value, arg_index = _get_prompt_value(user_prompt, args, kwargs)
+                
+                retry_count = 0
+                best_answer = None
+                current_prompt = prompt_value
+                
+                while retry_count <= max_retries:
+                    if retry_count == 0:
+                        logger.info("Generating initial answer...")
+                    else:
+                        logger.warning(f"Triggering reflection and rewrite, attempt {retry_count}...")
+                    
+                    new_args, new_kwargs = _update_prompt(current_prompt, arg_index, args, kwargs, user_prompt)
+                    answer = func(*new_args, **new_kwargs)
+                    best_answer = answer
+                    
+                    logger.info("Evaluating answer quality...")
+                    evaluation_result = rule.evaluate(prompt_value, answer)
+                    is_pass = evaluation_result.get("is_pass", False)
+                    feedback = evaluation_result.get("feedback", "")
+                    
+                    if is_pass:
+                        if retry_count > 0:
+                            logger.info("✅ Correction successful, returning the verified answer!")
+                        else:
+                            logger.info("✅ Initial draft is flawless, passing through!")
+                        return answer
+                    
+                    logger.error(f"❌ Hallucination or error detected: {feedback}")
+                    
+                    current_prompt = _generate_reflection_prompt(prompt_value, best_answer, feedback)
+                    retry_count += 1
+                
+                logger.warning("Maximum retries reached, executing fallback strategy.")
+                action_instance = on_fail() if isinstance(on_fail, type) else on_fail
+                return action_instance.execute(
+                    prompt=prompt_value, 
+                    last_answer=best_answer, 
+                    feedback=feedback
+                )
+            return sync_wrapper
+    return decorator
+
+# Add config method to verify function
+verify.config = Config

factlite-1.0.0/FactLite.egg-info/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: FactLite
+Version: 1.0.0
+Summary: A lightweight framework for fact-checking AI-generated content
+Author-email: SR思锐 团队 <srinternet@qq.com>
+License: MIT License
+        
+        Copyright (c) 2026 SR思锐 团队
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/SRInternet-Studio/FactLite
+Project-URL: Issues, https://github.com/SRInternet-Studio/FactLite/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0.0
+Dynamic: license-file
+
+# FactLite 🪶
+
+English | [中文](README_CN.md)
+
+**Give Your LLM a "System 2" Brain with a Single Decorator.**
+
+[![PyPI version](https://badge.fury.io/py/factlite.svg)](https://badge.fury.io/py/factlite)
+[![Build Status](https://travis-ci.org/your-username/factlite.svg?branch=main)](https://travis-ci.org/your-username/factlite)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/release/python-390/)
+
+---
+
+In the last mile of deploying Generative AI, **hallucination is the final boss**. Heavy frameworks like LangChain introduce too much boilerplate and complexity, while raw API calls offer no safety net.
+
+**FactLite** is a production-ready, feather-light Python micro-framework designed to solve this exact problem. It enhances your existing LLM calls with an automated, self-correcting evaluation loop, inspired by the top-tier **Agentic "Reflexion" Architecture**, without forcing you to refactor your codebase.
+
+## 🚀 Key Features
+
+*   **✨ Zero-Intrusion:** Add fact-checking and self-correction to any function with a single `@verify` decorator. No need to rewrite your existing logic.
+*   **⚡️ Async-Native & Concurrency Safe:** Built from the ground up to support `async/await`. The evaluation process runs in a separate thread to prevent blocking your main event loop, making it perfect for high-performance web backends like FastAPI.
+*   **🤖 Agentic Workflow:** Implements an automated **Generate -> Evaluate -> Reflect** loop. Your LLM is forced to critique and iteratively improve its own answers until they meet your quality standards.
+*   **🧩 Extensible & Pluggable:**
+    *   Bring your own judge! Use the built-in `LLMJudge` or create your own validation logic (e.g., regex, database lookups, type checks) with `CustomJudge`.
+    *   Define your own failure policies. Raise an error, return a safe message, or trigger a webhook with custom `FallbackAction`.
+*   **🌐 Framework Agnostic:** FactLite doesn't care how you call your LLM. Whether you're using the `openai` SDK, `anthropic`'s client, or a simple `requests.post` call to a local model, as long as it's a Python function that returns a string, FactLite can safeguard it.
+
+## 📦 Installation
+
+```bash
+pip install factlite
+```
+
+## 🎯 Quick Start: The "Aha!" Moment
+
+See how easy it is to upgrade your existing code from a simple API call to a self-correcting agent.
+
+**Before: A standard, unprotected LLM call.**
+
+```python
+import openai
+
+client = openai.OpenAI(api_key="your-key")
+
+def ask_ai(question: str):
+    response = client.chat.completions.create(
+        model="gpt-3.5-turbo",
+        messages=[{"role": "user", "content": question}]
+    )
+    return response.choices[0].message.content
+
+# This might return a factually incorrect answer, and you'd never know.
+print(ask_ai("Was Li Bai an emperor in the Song Dynasty?"))
+```
+
+**After: Protected by FactLite with a single line of code.**
+
+```python
+import openai
+from FactLite import verify, rules, action
+
+client = openai.OpenAI(api_key="your-key")
+
+# Configure a powerful judge and your API key
+config = verify.config(
+    api_key="your-key",
+    rule=rules.LLMJudge(model="gpt-4o-mini"),
+    max_retries=1
+)
+
+@verify(config=config, user_prompt="question") # Just add this decorator!
+def ask_ai(question: str):
+    response = client.chat.completions.create(
+        model="gpt-3.5-turbo",
+        messages=[{"role": "user", "content": question}]
+    )
+    return response.choices[0].message.content
+
+# Now, the function will automatically correct itself before returning.
+print(ask_ai("Was Li Bai an emperor in the Song Dynasty?"))
+```
+
+**What you'll see in your console:**
+
+```text
+10:30:05 - [FactLite] - Generating initial answer...
+10:30:08 - [FactLite] - Evaluating answer quality...
+10:30:12 - [FactLite] - ❌ Hallucination or error detected: The answer incorrectly states that Li Bai was related to the Song Dynasty. He was a poet from the Tang Dynasty.
+10:30:12 - [FactLite] - Triggering reflection and rewrite, attempt 1...
+10:30:16 - [FactLite] - Evaluating answer quality...
+10:30:19 - [FactLite] - ✅ Correction successful, returning the verified answer!
+
+No, Li Bai was not an emperor in the Song Dynasty. He was a renowned poet who lived during the Tang Dynasty (701-762 AD).
+```
+
+## 💡 Advanced Usage
+
+### Async Support
+
+FactLite automatically detects and supports `async` functions.
+
+```python
+from openai import AsyncOpenAI
+
+async_client = AsyncOpenAI(api_key="your-key")
+
+@verify(config=config, user_prompt="question")
+async def ask_ai_async(question: str):
+    response = await async_client.chat.completions.create(...)
+    return response.choices[0].message.content
+
+# Run it
+import asyncio
+asyncio.run(ask_ai_async("Tell me about the Tang Dynasty."))
+```
+
+### Custom Rules (`CustomJudge`)
+
+Go beyond LLM-based checks. Enforce any local business logic you can imagine.
+
+```python
+def company_policy_judge(prompt, answer):
+    # Rule 1: No short answers
+    if len(answer) < 50:
+        return {"is_pass": False, "feedback": "Answer is too short. Please be more detailed."}
+    # Rule 2: Don't mention competitors
+    if "Google" in answer:
+        return {"is_pass": False, "feedback": "Do not mention competitor names."}
+    return {"is_pass": True, "feedback": ""}
+
+@verify(rule=rules.CustomJudge(eval_func=company_policy_judge), user_prompt="prompt")
+def ask_support_bot(prompt: str):
+    # ... your LLM call
+    pass
+```
+
+### Custom Failure Actions (`FallbackAction`)
+
+Decide exactly what happens when an answer fails all retries.
+
+```python
+from FactLite import action
+
+@verify(
+    ...,
+    on_fail=action.ReturnSafeMessage("I'm sorry, I cannot provide a confident answer to that question at the moment.")
+)
+def ask_sensitive_question(...):
+    pass
+
+@verify(..., on_fail=action.RaiseError())
+def ask_critical_question(...):
+    pass
+```
+
+## 🛠️ How It Works
+
+FactLite's `@verify` decorator wraps your function in a simple yet powerful control loop:
+
+1.  **Generate**: Your original function is called to produce an initial draft.
+2.  **Evaluate**: The configured `rule` (e.g., `LLMJudge`) is invoked to assess the draft.
+3.  **Reflect & Retry**:
+    *   If the evaluation passes, the answer is returned to the user.
+    *   If it fails, the feedback is combined with the original prompt to create a "reflection prompt," forcing the LLM to correct its mistake. The process repeats from Step 1 until `max_retries` is reached.
+4.  **Fallback**: If all retries fail, the configured `on_fail` action is executed.
+
+## 🤝 Contributing
+
+Contributions are welcome! Whether it's a new rule, a new fallback action, or a performance improvement, feel free to open an issue or submit a pull request.
+
+## 📄 License
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.

factlite-1.0.0/FactLite.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+FactLite/__init__.py
+FactLite.egg-info/PKG-INFO
+FactLite.egg-info/SOURCES.txt
+FactLite.egg-info/dependency_links.txt
+FactLite.egg-info/requires.txt
+FactLite.egg-info/top_level.txt
+FactLite/core/actions.py
+FactLite/core/config.py
+FactLite/core/rules.py
+FactLite/core/verify.py

factlite-1.0.0/FactLite.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

factlite-1.0.0/FactLite.egg-info/requires.txt

@@ -0,0 +1 @@
+openai>=1.0.0

factlite-1.0.0/FactLite.egg-info/top_level.txt

@@ -0,0 +1 @@
+FactLite

factlite-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SR思锐 团队
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

factlite-1.0.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: FactLite
+Version: 1.0.0
+Summary: A lightweight framework for fact-checking AI-generated content
+Author-email: SR思锐 团队 <srinternet@qq.com>
+License: MIT License
+        
+        Copyright (c) 2026 SR思锐 团队
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/SRInternet-Studio/FactLite
+Project-URL: Issues, https://github.com/SRInternet-Studio/FactLite/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0.0
+Dynamic: license-file
+
+# FactLite 🪶
+
+English | [中文](README_CN.md)
+
+**Give Your LLM a "System 2" Brain with a Single Decorator.**
+
+[![PyPI version](https://badge.fury.io/py/factlite.svg)](https://badge.fury.io/py/factlite)
+[![Build Status](https://travis-ci.org/your-username/factlite.svg?branch=main)](https://travis-ci.org/your-username/factlite)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/release/python-390/)
+
+---
+
+In the last mile of deploying Generative AI, **hallucination is the final boss**. Heavy frameworks like LangChain introduce too much boilerplate and complexity, while raw API calls offer no safety net.
+
+**FactLite** is a production-ready, feather-light Python micro-framework designed to solve this exact problem. It enhances your existing LLM calls with an automated, self-correcting evaluation loop, inspired by the top-tier **Agentic "Reflexion" Architecture**, without forcing you to refactor your codebase.
+
+## 🚀 Key Features
+
+*   **✨ Zero-Intrusion:** Add fact-checking and self-correction to any function with a single `@verify` decorator. No need to rewrite your existing logic.
+*   **⚡️ Async-Native & Concurrency Safe:** Built from the ground up to support `async/await`. The evaluation process runs in a separate thread to prevent blocking your main event loop, making it perfect for high-performance web backends like FastAPI.
+*   **🤖 Agentic Workflow:** Implements an automated **Generate -> Evaluate -> Reflect** loop. Your LLM is forced to critique and iteratively improve its own answers until they meet your quality standards.
+*   **🧩 Extensible & Pluggable:**
+    *   Bring your own judge! Use the built-in `LLMJudge` or create your own validation logic (e.g., regex, database lookups, type checks) with `CustomJudge`.
+    *   Define your own failure policies. Raise an error, return a safe message, or trigger a webhook with custom `FallbackAction`.
+*   **🌐 Framework Agnostic:** FactLite doesn't care how you call your LLM. Whether you're using the `openai` SDK, `anthropic`'s client, or a simple `requests.post` call to a local model, as long as it's a Python function that returns a string, FactLite can safeguard it.
+
+## 📦 Installation
+
+```bash
+pip install factlite
+```
+
+## 🎯 Quick Start: The "Aha!" Moment
+
+See how easy it is to upgrade your existing code from a simple API call to a self-correcting agent.
+
+**Before: A standard, unprotected LLM call.**
+
+```python
+import openai
+
+client = openai.OpenAI(api_key="your-key")
+
+def ask_ai(question: str):
+    response = client.chat.completions.create(
+        model="gpt-3.5-turbo",
+        messages=[{"role": "user", "content": question}]
+    )
+    return response.choices[0].message.content
+
+# This might return a factually incorrect answer, and you'd never know.
+print(ask_ai("Was Li Bai an emperor in the Song Dynasty?"))
+```
+
+**After: Protected by FactLite with a single line of code.**
+
+```python
+import openai
+from FactLite import verify, rules, action
+
+client = openai.OpenAI(api_key="your-key")
+
+# Configure a powerful judge and your API key
+config = verify.config(
+    api_key="your-key",
+    rule=rules.LLMJudge(model="gpt-4o-mini"),
+    max_retries=1
+)
+
+@verify(config=config, user_prompt="question") # Just add this decorator!
+def ask_ai(question: str):
+    response = client.chat.completions.create(
+        model="gpt-3.5-turbo",
+        messages=[{"role": "user", "content": question}]
+    )
+    return response.choices[0].message.content
+
+# Now, the function will automatically correct itself before returning.
+print(ask_ai("Was Li Bai an emperor in the Song Dynasty?"))
+```
+
+**What you'll see in your console:**
+
+```text
+10:30:05 - [FactLite] - Generating initial answer...
+10:30:08 - [FactLite] - Evaluating answer quality...
+10:30:12 - [FactLite] - ❌ Hallucination or error detected: The answer incorrectly states that Li Bai was related to the Song Dynasty. He was a poet from the Tang Dynasty.
+10:30:12 - [FactLite] - Triggering reflection and rewrite, attempt 1...
+10:30:16 - [FactLite] - Evaluating answer quality...
+10:30:19 - [FactLite] - ✅ Correction successful, returning the verified answer!
+
+No, Li Bai was not an emperor in the Song Dynasty. He was a renowned poet who lived during the Tang Dynasty (701-762 AD).
+```
+
+## 💡 Advanced Usage
+
+### Async Support
+
+FactLite automatically detects and supports `async` functions.
+
+```python
+from openai import AsyncOpenAI
+
+async_client = AsyncOpenAI(api_key="your-key")
+
+@verify(config=config, user_prompt="question")
+async def ask_ai_async(question: str):
+    response = await async_client.chat.completions.create(...)
+    return response.choices[0].message.content
+
+# Run it
+import asyncio
+asyncio.run(ask_ai_async("Tell me about the Tang Dynasty."))
+```
+
+### Custom Rules (`CustomJudge`)
+
+Go beyond LLM-based checks. Enforce any local business logic you can imagine.
+
+```python
+def company_policy_judge(prompt, answer):
+    # Rule 1: No short answers
+    if len(answer) < 50:
+        return {"is_pass": False, "feedback": "Answer is too short. Please be more detailed."}
+    # Rule 2: Don't mention competitors
+    if "Google" in answer:
+        return {"is_pass": False, "feedback": "Do not mention competitor names."}
+    return {"is_pass": True, "feedback": ""}
+
+@verify(rule=rules.CustomJudge(eval_func=company_policy_judge), user_prompt="prompt")
+def ask_support_bot(prompt: str):
+    # ... your LLM call
+    pass
+```
+
+### Custom Failure Actions (`FallbackAction`)
+
+Decide exactly what happens when an answer fails all retries.
+
+```python
+from FactLite import action
+
+@verify(
+    ...,
+    on_fail=action.ReturnSafeMessage("I'm sorry, I cannot provide a confident answer to that question at the moment.")
+)
+def ask_sensitive_question(...):
+    pass
+
+@verify(..., on_fail=action.RaiseError())
+def ask_critical_question(...):
+    pass
+```
+
+## 🛠️ How It Works
+
+FactLite's `@verify` decorator wraps your function in a simple yet powerful control loop:
+
+1.  **Generate**: Your original function is called to produce an initial draft.
+2.  **Evaluate**: The configured `rule` (e.g., `LLMJudge`) is invoked to assess the draft.
+3.  **Reflect & Retry**:
+    *   If the evaluation passes, the answer is returned to the user.
+    *   If it fails, the feedback is combined with the original prompt to create a "reflection prompt," forcing the LLM to correct its mistake. The process repeats from Step 1 until `max_retries` is reached.
+4.  **Fallback**: If all retries fail, the configured `on_fail` action is executed.
+
+## 🤝 Contributing
+
+Contributions are welcome! Whether it's a new rule, a new fallback action, or a performance improvement, feel free to open an issue or submit a pull request.
+
+## 📄 License
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.

factlite-1.0.0/README.md

@@ -0,0 +1,173 @@
+# FactLite 🪶
+
+English | [中文](README_CN.md)
+
+**Give Your LLM a "System 2" Brain with a Single Decorator.**
+
+[![PyPI version](https://badge.fury.io/py/factlite.svg)](https://badge.fury.io/py/factlite)
+[![Build Status](https://travis-ci.org/your-username/factlite.svg?branch=main)](https://travis-ci.org/your-username/factlite)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/release/python-390/)
+
+---
+
+In the last mile of deploying Generative AI, **hallucination is the final boss**. Heavy frameworks like LangChain introduce too much boilerplate and complexity, while raw API calls offer no safety net.
+
+**FactLite** is a production-ready, feather-light Python micro-framework designed to solve this exact problem. It enhances your existing LLM calls with an automated, self-correcting evaluation loop, inspired by the top-tier **Agentic "Reflexion" Architecture**, without forcing you to refactor your codebase.
+
+## 🚀 Key Features
+
+*   **✨ Zero-Intrusion:** Add fact-checking and self-correction to any function with a single `@verify` decorator. No need to rewrite your existing logic.
+*   **⚡️ Async-Native & Concurrency Safe:** Built from the ground up to support `async/await`. The evaluation process runs in a separate thread to prevent blocking your main event loop, making it perfect for high-performance web backends like FastAPI.
+*   **🤖 Agentic Workflow:** Implements an automated **Generate -> Evaluate -> Reflect** loop. Your LLM is forced to critique and iteratively improve its own answers until they meet your quality standards.
+*   **🧩 Extensible & Pluggable:**
+    *   Bring your own judge! Use the built-in `LLMJudge` or create your own validation logic (e.g., regex, database lookups, type checks) with `CustomJudge`.
+    *   Define your own failure policies. Raise an error, return a safe message, or trigger a webhook with custom `FallbackAction`.
+*   **🌐 Framework Agnostic:** FactLite doesn't care how you call your LLM. Whether you're using the `openai` SDK, `anthropic`'s client, or a simple `requests.post` call to a local model, as long as it's a Python function that returns a string, FactLite can safeguard it.
+
+## 📦 Installation
+
+```bash
+pip install factlite
+```
+
+## 🎯 Quick Start: The "Aha!" Moment
+
+See how easy it is to upgrade your existing code from a simple API call to a self-correcting agent.
+
+**Before: A standard, unprotected LLM call.**
+
+```python
+import openai
+
+client = openai.OpenAI(api_key="your-key")
+
+def ask_ai(question: str):
+    response = client.chat.completions.create(
+        model="gpt-3.5-turbo",
+        messages=[{"role": "user", "content": question}]
+    )
+    return response.choices[0].message.content
+
+# This might return a factually incorrect answer, and you'd never know.
+print(ask_ai("Was Li Bai an emperor in the Song Dynasty?"))
+```
+
+**After: Protected by FactLite with a single line of code.**
+
+```python
+import openai
+from FactLite import verify, rules, action
+
+client = openai.OpenAI(api_key="your-key")
+
+# Configure a powerful judge and your API key
+config = verify.config(
+    api_key="your-key",
+    rule=rules.LLMJudge(model="gpt-4o-mini"),
+    max_retries=1
+)
+
+@verify(config=config, user_prompt="question") # Just add this decorator!
+def ask_ai(question: str):
+    response = client.chat.completions.create(
+        model="gpt-3.5-turbo",
+        messages=[{"role": "user", "content": question}]
+    )
+    return response.choices[0].message.content
+
+# Now, the function will automatically correct itself before returning.
+print(ask_ai("Was Li Bai an emperor in the Song Dynasty?"))
+```
+
+**What you'll see in your console:**
+
+```text
+10:30:05 - [FactLite] - Generating initial answer...
+10:30:08 - [FactLite] - Evaluating answer quality...
+10:30:12 - [FactLite] - ❌ Hallucination or error detected: The answer incorrectly states that Li Bai was related to the Song Dynasty. He was a poet from the Tang Dynasty.
+10:30:12 - [FactLite] - Triggering reflection and rewrite, attempt 1...
+10:30:16 - [FactLite] - Evaluating answer quality...
+10:30:19 - [FactLite] - ✅ Correction successful, returning the verified answer!
+
+No, Li Bai was not an emperor in the Song Dynasty. He was a renowned poet who lived during the Tang Dynasty (701-762 AD).
+```
+
+## 💡 Advanced Usage
+
+### Async Support
+
+FactLite automatically detects and supports `async` functions.
+
+```python
+from openai import AsyncOpenAI
+
+async_client = AsyncOpenAI(api_key="your-key")
+
+@verify(config=config, user_prompt="question")
+async def ask_ai_async(question: str):
+    response = await async_client.chat.completions.create(...)
+    return response.choices[0].message.content
+
+# Run it
+import asyncio
+asyncio.run(ask_ai_async("Tell me about the Tang Dynasty."))
+```
+
+### Custom Rules (`CustomJudge`)
+
+Go beyond LLM-based checks. Enforce any local business logic you can imagine.
+
+```python
+def company_policy_judge(prompt, answer):
+    # Rule 1: No short answers
+    if len(answer) < 50:
+        return {"is_pass": False, "feedback": "Answer is too short. Please be more detailed."}
+    # Rule 2: Don't mention competitors
+    if "Google" in answer:
+        return {"is_pass": False, "feedback": "Do not mention competitor names."}
+    return {"is_pass": True, "feedback": ""}
+
+@verify(rule=rules.CustomJudge(eval_func=company_policy_judge), user_prompt="prompt")
+def ask_support_bot(prompt: str):
+    # ... your LLM call
+    pass
+```
+
+### Custom Failure Actions (`FallbackAction`)
+
+Decide exactly what happens when an answer fails all retries.
+
+```python
+from FactLite import action
+
+@verify(
+    ...,
+    on_fail=action.ReturnSafeMessage("I'm sorry, I cannot provide a confident answer to that question at the moment.")
+)
+def ask_sensitive_question(...):
+    pass
+
+@verify(..., on_fail=action.RaiseError())
+def ask_critical_question(...):
+    pass
+```
+
+## 🛠️ How It Works
+
+FactLite's `@verify` decorator wraps your function in a simple yet powerful control loop:
+
+1.  **Generate**: Your original function is called to produce an initial draft.
+2.  **Evaluate**: The configured `rule` (e.g., `LLMJudge`) is invoked to assess the draft.
+3.  **Reflect & Retry**:
+    *   If the evaluation passes, the answer is returned to the user.
+    *   If it fails, the feedback is combined with the original prompt to create a "reflection prompt," forcing the LLM to correct its mistake. The process repeats from Step 1 until `max_retries` is reached.
+4.  **Fallback**: If all retries fail, the configured `on_fail` action is executed.
+
+## 🤝 Contributing
+
+Contributions are welcome! Whether it's a new rule, a new fallback action, or a performance improvement, feel free to open an issue or submit a pull request.
+
+## 📄 License
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.

factlite-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "FactLite"
+version = "1.0.0"
+description = "A lightweight framework for fact-checking AI-generated content"
+readme = "README.md"
+authors = [
+    { name = "SR思锐 团队", email = "srinternet@qq.com" },
+]
+license = { file = "LICENSE" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "openai>=1.0.0",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/SRInternet-Studio/FactLite"
+"Issues" = "https://github.com/SRInternet-Studio/FactLite/issues"

factlite-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+