fabricatio 0.3.14.dev0__cp312-cp312-win_amd64.whl → 0.3.14.dev2__cp312-cp312-win_amd64.whl

fabricatio/capabilities/check.py

@@ -1,10 +1,9 @@
 """A class that provides the capability to check strings and objects against rules and guidelines."""
 
+from abc import ABC
 from asyncio import gather
 from typing import List, Optional, Unpack
 
-from fabricatio.rust import CONFIG, TEMPLATE_MANAGER, detect_language
-
 from fabricatio.capabilities.advanced_judge import AdvancedJudge
 from fabricatio.capabilities.propose import Propose
 from fabricatio.journal import logger
@@ -13,10 +12,11 @@ from fabricatio.models.extra.problem import Improvement
 from fabricatio.models.extra.rule import Rule, RuleSet
 from fabricatio.models.generic import Display, WithBriefing
 from fabricatio.models.kwargs_types import ValidateKwargs
+from fabricatio.rust import CONFIG, TEMPLATE_MANAGER, detect_language
 from fabricatio.utils import override_kwargs
 
 
-class Check(AdvancedJudge, Propose):
+class Check(AdvancedJudge, Propose, ABC):
     """Class for validating strings/objects against predefined rules and guidelines.
 
     This capability combines rule-based judgment and proposal generation to provide
@@ -24,7 +24,7 @@ class Check(AdvancedJudge, Propose):
     """
 
     async def draft_ruleset(
-            self, ruleset_requirement: str, rule_count: int = 0, **kwargs: Unpack[ValidateKwargs[Rule]]
+        self, ruleset_requirement: str, rule_count: int = 0, **kwargs: Unpack[ValidateKwargs[Rule]]
     ) -> Optional[RuleSet]:
         """Generate rule set based on requirement description.
 
@@ -80,11 +80,11 @@ class Check(AdvancedJudge, Propose):
         return RuleSet(rules=rules, **ruleset_patch.as_kwargs())
 
     async def check_string_against_rule(
-            self,
-            input_text: str,
-            rule: Rule,
-            reference: str = "",
-            **kwargs: Unpack[ValidateKwargs[Improvement]],
+        self,
+        input_text: str,
+        rule: Rule,
+        reference: str = "",
+        **kwargs: Unpack[ValidateKwargs[Improvement]],
     ) -> Optional[Improvement]:
         """Validate text against specific rule.
 
@@ -103,9 +103,9 @@ class Check(AdvancedJudge, Propose):
             - Proposes Improvement only when violation is confirmed
         """
         if judge := await self.evidently_judge(
-                f"# Content to exam\n{input_text}\n\n# Rule Must to follow\n{rule.display()}\nDoes `Content to exam` provided above violate the `{rule.name}` provided above?"
-                f"should I take some measure to fix that violation? true for I do need, false for I don't need.",
-                **override_kwargs(kwargs, default=None),
+            f"# Content to exam\n{input_text}\n\n# Rule Must to follow\n{rule.display()}\nDoes `Content to exam` provided above violate the `{rule.name}` provided above?"
+            f"should I take some measure to fix that violation? true for I do need, false for I don't need.",
+            **override_kwargs(kwargs, default=None),
         ):
             logger.info(f"Rule `{rule.name}` violated: \n{judge.display()}")
             return await self.propose(
@@ -119,11 +119,11 @@ class Check(AdvancedJudge, Propose):
         return None
 
     async def check_obj_against_rule[M: (Display, WithBriefing)](
-            self,
-            obj: M,
-            rule: Rule,
-            reference: str = "",
-            **kwargs: Unpack[ValidateKwargs[Improvement]],
+        self,
+        obj: M,
+        rule: Rule,
+        reference: str = "",
+        **kwargs: Unpack[ValidateKwargs[Improvement]],
     ) -> Optional[Improvement]:
         """Validate object against rule using text representation.
 
@@ -151,11 +151,11 @@ class Check(AdvancedJudge, Propose):
         return await self.check_string_against_rule(input_text, rule, reference, **kwargs)
 
     async def check_string(
-            self,
-            input_text: str,
-            ruleset: RuleSet,
-            reference: str = "",
-            **kwargs: Unpack[ValidateKwargs[Improvement]],
+        self,
+        input_text: str,
+        ruleset: RuleSet,
+        reference: str = "",
+        **kwargs: Unpack[ValidateKwargs[Improvement]],
     ) -> Optional[List[Improvement]]:
         """Validate text against full ruleset.
 
@@ -182,11 +182,11 @@ class Check(AdvancedJudge, Propose):
         return [imp for imp in imp_seq if imp]
 
     async def check_obj[M: (Display, WithBriefing)](
-            self,
-            obj: M,
-            ruleset: RuleSet,
-            reference: str = "",
-            **kwargs: Unpack[ValidateKwargs[Improvement]],
+        self,
+        obj: M,
+        ruleset: RuleSet,
+        reference: str = "",
+        **kwargs: Unpack[ValidateKwargs[Improvement]],
     ) -> Optional[List[Improvement]]:
         """Validate object against full ruleset.
 

fabricatio/capabilities/correct.py

@@ -1,9 +1,8 @@
 """A module containing the Correct capability for reviewing, validating, and improving objects."""
 
+from abc import ABC
 from asyncio import gather
-from typing import Optional, Unpack, cast
-
-from fabricatio.rust import CONFIG, TEMPLATE_MANAGER
+from typing import Optional, Type, Unpack, cast
 
 from fabricatio.capabilities.propose import Propose
 from fabricatio.capabilities.rating import Rating
@@ -15,14 +14,15 @@ from fabricatio.models.kwargs_types import (
     BestKwargs,
     ValidateKwargs,
 )
+from fabricatio.rust import CONFIG, TEMPLATE_MANAGER
 from fabricatio.utils import fallback_kwargs, ok, override_kwargs
 
 
-class Correct(Rating, Propose):
+class Correct(Rating, Propose, ABC):
     """A class that provides the capability to correct objects."""
 
     async def decide_solution(
-            self, problem_solutions: ProblemSolutions, **kwargs: Unpack[BestKwargs]
+        self, problem_solutions: ProblemSolutions, **kwargs: Unpack[BestKwargs]
     ) -> ProblemSolutions:
         """Decide the best solution from a list of problem solutions.
 
@@ -72,11 +72,11 @@ class Correct(Rating, Propose):
         return improvement
 
     async def fix_troubled_obj[M: SketchedAble](
-            self,
-            obj: M,
-            problem_solutions: ProblemSolutions,
-            reference: str = "",
-            **kwargs: Unpack[ValidateKwargs[M]],
+        self,
+        obj: M,
+        problem_solutions: ProblemSolutions,
+        reference: str = "",
+        **kwargs: Unpack[ValidateKwargs[M]],
     ) -> Optional[M]:
         """Fix a troubled object based on problem solutions.
 
@@ -106,11 +106,11 @@ class Correct(Rating, Propose):
         )
 
     async def fix_troubled_string(
-            self,
-            input_text: str,
-            problem_solutions: ProblemSolutions,
-            reference: str = "",
-            **kwargs: Unpack[ValidateKwargs[str]],
+        self,
+        input_text: str,
+        problem_solutions: ProblemSolutions,
+        reference: str = "",
+        **kwargs: Unpack[ValidateKwargs[str]],
     ) -> Optional[str]:
         """Fix a troubled string based on problem solutions.
 
@@ -140,11 +140,11 @@ class Correct(Rating, Propose):
         )
 
     async def correct_obj[M: SketchedAble](
-            self,
-            obj: M,
-            improvement: Improvement,
-            reference: str = "",
-            **kwargs: Unpack[ValidateKwargs[M]],
+        self,
+        obj: M,
+        improvement: Improvement,
+        reference: str = "",
+        **kwargs: Unpack[ValidateKwargs[M]],
     ) -> Optional[M]:
         """Review and correct an object based on defined criteria and templates.
 
@@ -178,7 +178,7 @@ class Correct(Rating, Propose):
         return obj
 
     async def correct_string(
-            self, input_text: str, improvement: Improvement, reference: str = "", **kwargs: Unpack[ValidateKwargs[str]]
+        self, input_text: str, improvement: Improvement, reference: str = "", **kwargs: Unpack[ValidateKwargs[str]]
     ) -> Optional[str]:
         """Review and correct a string based on defined criteria and templates.
 
@@ -210,7 +210,7 @@ class Correct(Rating, Propose):
         return input_text
 
     async def correct_obj_inplace[M: ProposedUpdateAble](
-            self, obj: M, **kwargs: Unpack[CorrectKwargs[M]]
+        self, obj: M, **kwargs: Unpack[CorrectKwargs[M]]
     ) -> Optional[M]:
         """Correct an object in place based on defined criteria and templates.
 

fabricatio/capabilities/extract.py

@@ -1,65 +1,65 @@
 """A module that provide capabilities for extracting information from a given source to a model."""
 
+from abc import ABC
 from typing import List, Optional, Type, Unpack, overload
 
-from fabricatio.rust import CONFIG
-
 from fabricatio import TEMPLATE_MANAGER
 from fabricatio.capabilities.propose import Propose
 from fabricatio.models.generic import ProposedAble
 from fabricatio.models.kwargs_types import ValidateKwargs
+from fabricatio.rust import CONFIG
 
 
-class Extract(Propose):
+class Extract(Propose, ABC):
     """A class that extract information from a given source to a model."""
 
     @overload
     async def extract[M: ProposedAble](
-            self,
-            cls: Type[M],
-            source: str,
-            extract_requirement: Optional[str] = None,
-            align_language: bool = True,
-            **kwargs: Unpack[ValidateKwargs[M]],
+        self,
+        cls: Type[M],
+        source: str,
+        extract_requirement: Optional[str] = None,
+        align_language: bool = True,
+        **kwargs: Unpack[ValidateKwargs[M]],
     ) -> M: ...
 
     @overload
     async def extract[M: ProposedAble](
-            self,
-            cls: Type[M],
-            source: str,
-            extract_requirement: Optional[str] = None,
-            align_language: bool = True,
-            **kwargs: Unpack[ValidateKwargs[None]],
+        self,
+        cls: Type[M],
+        source: str,
+        extract_requirement: Optional[str] = None,
+        align_language: bool = True,
+        **kwargs: Unpack[ValidateKwargs[None]],
     ) -> Optional[M]: ...
 
     @overload
     async def extract[M: ProposedAble](
-            self,
-            cls: Type[M],
-            source: List[str],
-            extract_requirement: Optional[str] = None,
-            align_language: bool = True,
-            **kwargs: Unpack[ValidateKwargs[M]],
+        self,
+        cls: Type[M],
+        source: List[str],
+        extract_requirement: Optional[str] = None,
+        align_language: bool = True,
+        **kwargs: Unpack[ValidateKwargs[M]],
     ) -> List[M]: ...
 
     @overload
     async def extract[M: ProposedAble](
-            self,
-            cls: Type[M],
-            source: List[str],
-            extract_requirement: Optional[str] = None,
-            align_language: bool = True,
-            **kwargs: Unpack[ValidateKwargs[None]],
+        self,
+        cls: Type[M],
+        source: List[str],
+        extract_requirement: Optional[str] = None,
+        align_language: bool = True,
+        **kwargs: Unpack[ValidateKwargs[None]],
     ) -> List[Optional[M]]: ...
 
     async def extract[M: ProposedAble](
-            self,
-            cls: Type[M],
-            source: List[str] | str,
-            extract_requirement: Optional[str] = None,
-            align_language: bool = True,
-            **kwargs: Unpack[ValidateKwargs[Optional[M]]],
+        self,
+        cls: Type[M],
+        source: List[str] | str,
+        extract_requirement: Optional[str] = None,
+        align_language: bool = True,
+        **kwargs: Unpack[ValidateKwargs[Optional[M]]],
     ) -> M | List[M] | Optional[M] | List[Optional[M]]:
         """Extract information from a given source to a model."""
         return await self.propose(

fabricatio/capabilities/persist.py

@@ -0,0 +1,103 @@
+"""Persistence capabilities for model instances."""
+
+from abc import ABC
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Self
+
+from loguru import logger
+
+from fabricatio.fs import safe_text_read
+from fabricatio.models.generic import Base
+from fabricatio.rust import blake3_hash
+
+
+class PersistentAble(Base, ABC):
+    """Class providing file persistence capabilities.
+
+    Enables saving model instances to disk with timestamped filenames and loading from persisted files.
+    Implements basic versioning through filename hashing and timestamping.
+    """
+
+    def persist(self, path: str | Path) -> Self:
+        """Save model instance to disk with versioned filename.
+
+        Args:
+            path (str | Path): Target directory or file path. If directory, filename is auto-generated.
+
+        Returns:
+            Self: Current instance for method chaining
+
+        Notes:
+            - Filename format: <ClassName>_<YYYYMMDD_HHMMSS>_<6-char_hash>.json
+            - Hash generated from JSON content ensures uniqueness
+        """
+        p = Path(path)
+        out = self.model_dump_json(indent=1, by_alias=True)
+
+        # Generate a timestamp in the format YYYYMMDD_HHMMSS
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+
+        # Generate the hash
+        file_hash = blake3_hash(out.encode())[:6]
+
+        # Construct the file name with timestamp and hash
+        file_name = f"{self.__class__.__name__}_{timestamp}_{file_hash}.json"
+
+        if p.is_dir():
+            p.joinpath(file_name).write_text(out, encoding="utf-8")
+        else:
+            p.mkdir(exist_ok=True, parents=True)
+            p.write_text(out, encoding="utf-8")
+
+        logger.info(f"Persisted `{self.__class__.__name__}` to {p.as_posix()}")
+        return self
+
+    @classmethod
+    def from_latest_persistent(cls, dir_path: str | Path) -> Optional[Self]:
+        """Load most recent persisted instance from directory.
+
+        Args:
+            dir_path (str | Path): Directory containing persisted files
+
+        Returns:
+            Self: Most recently modified instance
+
+        Raises:
+            NotADirectoryError: If path is not a valid directory
+            FileNotFoundError: If no matching files found
+        """
+        dir_path = Path(dir_path)
+        if not dir_path.is_dir():
+            return None
+
+        pattern = f"{cls.__name__}_*.json"
+        files = list(dir_path.glob(pattern))
+
+        if not files:
+            return None
+
+        def _get_timestamp(file_path: Path) -> datetime:
+            stem = file_path.stem
+            parts = stem.split("_")
+            return datetime.strptime(f"{parts[1]}_{parts[2]}", "%Y%m%d_%H%M%S")
+
+        files.sort(key=lambda f: _get_timestamp(f), reverse=True)
+
+        return cls.from_persistent(files.pop(0))
+
+    @classmethod
+    def from_persistent(cls, path: str | Path) -> Self:
+        """Load an instance from a specific persisted file.
+
+        Args:
+            path (str | Path): Path to the JSON file.
+
+        Returns:
+            Self: The loaded instance from the file.
+
+        Raises:
+            FileNotFoundError: If the specified file does not exist.
+            ValueError: If the file content is invalid for the model.
+        """
+        return cls.model_validate_json(safe_text_read(path))

fabricatio/capabilities/propose.py

@@ -1,5 +1,5 @@
 """A module for the task capabilities of the Fabricatio library."""
-
+from abc import ABC
 from typing import List, Optional, Type, Unpack, overload
 
 from fabricatio.models.generic import ProposedAble
@@ -7,7 +7,7 @@ from fabricatio.models.kwargs_types import ValidateKwargs
 from fabricatio.models.usages import LLMUsage
 
 
-class Propose(LLMUsage):
+class Propose(LLMUsage,ABC):
     """A class that proposes an Obj based on a prompt."""
 
     @overload

fabricatio/capabilities/rag.py

@@ -1,5 +1,7 @@
 """A module for the RAG (Retrieval Augmented Generation) model."""
 
+from abc import ABC
+
 try:
     from pymilvus import MilvusClient
 except ImportError as e:
@@ -10,7 +12,6 @@ from functools import lru_cache
 from operator import itemgetter
 from typing import List, Optional, Self, Type, Unpack
 
-from fabricatio.rust import CONFIG, TEMPLATE_MANAGER
 from more_itertools.recipes import flatten, unique
 from pydantic import Field, PrivateAttr
 
@@ -19,6 +20,7 @@ from fabricatio.models.adv_kwargs_types import CollectionConfigKwargs, FetchKwar
 from fabricatio.models.extra.rag import MilvusDataBase
 from fabricatio.models.kwargs_types import ChooseKwargs
 from fabricatio.models.usages import EmbeddingUsage
+from fabricatio.rust import CONFIG, TEMPLATE_MANAGER
 from fabricatio.utils import ok
 
 
@@ -32,7 +34,7 @@ def create_client(uri: str, token: str = "", timeout: Optional[float] = None) ->
     )
 
 
-class RAG(EmbeddingUsage):
+class RAG(EmbeddingUsage, ABC):
     """A class representing the RAG (Retrieval Augmented Generation) model."""
 
     target_collection: Optional[str] = Field(default=None)
@@ -49,16 +51,16 @@ class RAG(EmbeddingUsage):
         return self._client
 
     def init_client(
-            self,
-            milvus_uri: Optional[str] = None,
-            milvus_token: Optional[str] = None,
-            milvus_timeout: Optional[float] = None,
+        self,
+        milvus_uri: Optional[str] = None,
+        milvus_token: Optional[str] = None,
+        milvus_timeout: Optional[float] = None,
     ) -> Self:
         """Initialize the Milvus client."""
         self._client = create_client(
-            uri=milvus_uri or ok(self.milvus_uri or CONFIG.rag.milvus_uri).unicode_string(),
+            uri=milvus_uri or ok(self.milvus_uri or CONFIG.rag.milvus_uri),
             token=milvus_token
-                  or (token.get_secret_value() if (token := (self.milvus_token or CONFIG.rag.milvus_token)) else ""),
+            or (token.get_secret_value() if (token := (self.milvus_token or CONFIG.rag.milvus_token)) else ""),
             timeout=milvus_timeout or self.milvus_timeout or CONFIG.rag.milvus_timeout,
         )
         return self
@@ -72,7 +74,7 @@ class RAG(EmbeddingUsage):
         return self
 
     def view(
-            self, collection_name: Optional[str], create: bool = False, **kwargs: Unpack[CollectionConfigKwargs]
+        self, collection_name: Optional[str], create: bool = False, **kwargs: Unpack[CollectionConfigKwargs]
     ) -> Self:
         """View the specified collection.
 
@@ -114,7 +116,7 @@ class RAG(EmbeddingUsage):
         return ok(self.target_collection, "No collection is being viewed. Have you called `self.view()`?")
 
     async def add_document[D: MilvusDataBase](
-            self, data: List[D] | D, collection_name: Optional[str] = None, flush: bool = False
+        self, data: List[D] | D, collection_name: Optional[str] = None, flush: bool = False
     ) -> Self:
         """Adds a document to the specified collection.
 
@@ -141,15 +143,15 @@ class RAG(EmbeddingUsage):
         return self
 
     async def afetch_document[D: MilvusDataBase](
-            self,
-            query: List[str],
-            document_model: Type[D],
-            collection_name: Optional[str] = None,
-            similarity_threshold: float = 0.37,
-            result_per_query: int = 10,
-            tei_endpoint: Optional[str] = None,
-            reranker_threshold: float = 0.7,
-            filter_expr: str = "",
+        self,
+        query: List[str],
+        document_model: Type[D],
+        collection_name: Optional[str] = None,
+        similarity_threshold: float = 0.37,
+        result_per_query: int = 10,
+        tei_endpoint: Optional[str] = None,
+        reranker_threshold: float = 0.7,
+        filter_expr: str = "",
     ) -> List[D]:
         """Asynchronously fetches documents from a Milvus database based on input vectors.
 
@@ -162,7 +164,7 @@ class RAG(EmbeddingUsage):
            result_per_query (int): The maximum number of results to return per query. Defaults to 10.
            tei_endpoint (str): the endpoint of the TEI api.
            reranker_threshold (float): The threshold used to filtered low relativity document.
-            filter_expr (str): filter_expression parsed into pymilvus search.
+           filter_expr (str) : The filter expression used to filter out unwanted documents.
 
         Returns:
            List[D]: A list of document objects created from the fetched data.
@@ -177,9 +179,9 @@ class RAG(EmbeddingUsage):
             limit=result_per_query,
         )
         if tei_endpoint is not None:
-            from fabricatio.utils import RerankerAPI
+            from fabricatio.rust import TEIClient
 
-            reranker = RerankerAPI(base_url=tei_endpoint)
+            reranker = TEIClient(base_url=tei_endpoint)
 
             retrieved_id = set()
             raw_result = []
@@ -191,9 +193,7 @@ class RAG(EmbeddingUsage):
                 if not models:
                     continue
                 rank_scores = await reranker.arerank(q, [m.prepare_vectorization() for m in models], truncate=True)
-                raw_result.extend(
-                    (models[s["index"]], s["score"]) for s in rank_scores if s["score"] > reranker_threshold
-                )
+                raw_result.extend((models[idx], scr) for (idx, scr) in rank_scores if scr > reranker_threshold)
 
             raw_result_sorted = sorted(raw_result, key=lambda x: x[1], reverse=True)
             return [r[0] for r in raw_result_sorted]
@@ -214,11 +214,11 @@ class RAG(EmbeddingUsage):
         return document_model.from_sequence(resp)
 
     async def aretrieve[D: MilvusDataBase](
-            self,
-            query: List[str] | str,
-            document_model: Type[D],
-            max_accepted: int = 20,
-            **kwargs: Unpack[FetchKwargs],
+        self,
+        query: List[str] | str,
+        document_model: Type[D],
+        max_accepted: int = 20,
+        **kwargs: Unpack[FetchKwargs],
     ) -> List[D]:
         """Retrieve data from the collection.
 
@@ -235,15 +235,15 @@ class RAG(EmbeddingUsage):
             query = [query]
 
         return (
-                   await self.afetch_document(
-                       query=query,
-                       document_model=document_model,
-                       **kwargs,
-                   )
-               )[:max_accepted]
+            await self.afetch_document(
+                query=query,
+                document_model=document_model,
+                **kwargs,
+            )
+        )[:max_accepted]
 
     async def arefined_query(
-            self, question: List[str] | str, **kwargs: Unpack[ChooseKwargs[Optional[List[str]]]]
+        self, question: List[str] | str, **kwargs: Unpack[ChooseKwargs[Optional[List[str]]]]
     ) -> Optional[List[str]]:
         """Refines the given question using a template.