pixie-prompts 0.1.1__py3-none-any.whl

pixie/prompts/storage.py

@@ -0,0 +1,399 @@
+import json
+import logging
+import os
+from dataclasses import dataclass
+from types import NoneType
+from typing import Any, Dict, NotRequired, Protocol, Self, TypedDict
+
+from jsonsubschema import isSubschema
+
+from .prompt import (
+    BasePrompt,
+    BaseUntypedPrompt,
+    Prompt,
+    TPromptVar,
+    variables_definition_to_schema,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+VERSION_FILE_EXTENSION = ".jinja"
+
+
+@dataclass(frozen=True)
+class _PromptLoadFailure:
+    prompt_id: str | None
+    path: str
+    error: Exception
+
+
+class PromptLoadError(Exception):
+
+    def __init__(self, failures: list[_PromptLoadFailure]):
+        self.failures = failures
+        message_lines = [
+            f"- {failure.prompt_id or '<unknown>'} ({failure.path}): {failure.error}"
+            for failure in failures
+        ]
+        message = "Failed to load prompts:\n" + "\n".join(message_lines)
+        super().__init__(message)
+
+
+class BaseUntypedPromptWithCreationTime(BaseUntypedPrompt):
+
+    def __init__(
+        self,
+        *,
+        id: str,
+        versions: dict[str, str],
+        default_version_id: str,
+        variables_schema: dict[str, Any] | None = None,
+        version_creation_times: dict[str, float],
+    ) -> None:
+        super().__init__(
+            id=id,
+            versions=versions,
+            default_version_id=default_version_id,
+            variables_schema=variables_schema,
+        )
+        self._version_creation_times = version_creation_times
+
+    def get_version_creation_time(self, version_id: str) -> float:
+        return self._version_creation_times[version_id]
+
+
+class PromptStorage(Protocol):
+
+    def load(self, *, raise_on_error: bool = True) -> list[_PromptLoadFailure]: ...
+
+    def exists(self, prompt_id: str) -> bool: ...
+
+    def save(self, prompt: BaseUntypedPrompt) -> bool: ...
+
+    def get(self, prompt_id: str) -> BaseUntypedPromptWithCreationTime: ...
+
+
+class _BasePromptMetadata(TypedDict):
+    defaultVersionId: str
+    variablesSchema: NotRequired[Dict[str, Any]]
+
+
+class _FilePromptStorage(PromptStorage):
+
+    def __init__(self, directory: str, *, raise_on_error: bool = True) -> None:
+        self._directory = directory
+        self._prompts: Dict[str, BaseUntypedPromptWithCreationTime] = {}
+        self._load_failures: list[_PromptLoadFailure] = []
+        self.load(raise_on_error=raise_on_error)
+
+    def load(self, *, raise_on_error: bool = True) -> list[_PromptLoadFailure]:
+        """Load prompts from storage with error isolation.
+
+        Continues loading valid prompts even if some fail and aggregates failures.
+        """
+        logger.info("Loading prompts from directory %s", self._directory)
+        self._prompts.clear()
+        self._load_failures = []
+        if not os.path.exists(self._directory):
+            os.makedirs(self._directory)
+        for entry in os.listdir(self._directory):
+            prompt_path = os.path.join(self._directory, entry)
+            if not os.path.isdir(prompt_path):
+                logger.debug("Skipping non-directory entry at %s", prompt_path)
+                continue
+            try:
+                metadata_path = os.path.join(prompt_path, "metadata.json")
+                metadata: _BasePromptMetadata | None = None
+                if os.path.isfile(metadata_path):
+                    with open(metadata_path, "r") as f:
+                        metadata = json.load(f)
+
+                versions: dict[str, str] = {}
+                version_creation_times: dict[str, float] = {}
+                for filename in os.listdir(prompt_path):
+                    if not filename.endswith(VERSION_FILE_EXTENSION):
+                        continue
+                    version_id, _ = os.path.splitext(filename)
+                    version_path = os.path.join(prompt_path, filename)
+                    with open(version_path, "r") as vf:
+                        versions[version_id] = vf.read()
+                    version_creation_times[version_id] = os.path.getctime(version_path)
+
+                if not versions:
+                    raise KeyError("No versions provided for the prompt.")
+
+                if metadata is not None:
+                    default_version_id = metadata["defaultVersionId"]
+                    variables_schema = metadata.get("variablesSchema", None)
+                else:
+                    default_version_id, _ = max(
+                        version_creation_times.items(),
+                        key=lambda item: (item[1], item[0]),
+                    )
+                    variables_schema = None
+
+                if default_version_id not in versions:
+                    raise KeyError(
+                        f"Default version '{default_version_id}' not found for prompt '{entry}'."
+                    )
+
+                prompt = BaseUntypedPromptWithCreationTime(
+                    id=entry,
+                    versions=versions,
+                    default_version_id=default_version_id,
+                    variables_schema=variables_schema,
+                    version_creation_times=version_creation_times,
+                )
+                self._prompts[entry] = prompt
+                logger.debug(
+                    "Loaded prompt '%s' with %d version(s)", entry, len(versions)
+                )
+            except Exception as exc:  # noqa: BLE001
+                logger.exception("Failed to load prompt '%s' at %s", entry, prompt_path)
+                self._load_failures.append(
+                    _PromptLoadFailure(prompt_id=entry, path=prompt_path, error=exc)
+                )
+        if self._load_failures:
+            logger.warning(
+                "Completed loading prompts with %d failure(s)", len(self._load_failures)
+            )
+            if raise_on_error:
+                raise PromptLoadError(self._load_failures)
+        else:
+            logger.info("Loaded %d prompt(s) successfully", len(self._prompts))
+        return list(self._load_failures)
+
+    @property
+    def load_failures(self) -> list[_PromptLoadFailure]:
+        return list(self._load_failures)
+
+    def exists(self, prompt_id: str) -> bool:
+        return prompt_id in self._prompts
+
+    def save(self, prompt: BaseUntypedPrompt) -> bool:
+        prompt_id = prompt.id
+        original = self._prompts.get(prompt_id)
+        new_schema = prompt.get_variables_schema()
+        if original:
+            original_schema = original.get_variables_schema()
+            if not isSubschema(original_schema, new_schema):
+                raise TypeError(
+                    "Original schema must be a subschema of the new schema."
+                )
+        prompt_dir = os.path.join(self._directory, prompt_id)
+        os.makedirs(prompt_dir, exist_ok=True)
+
+        versions = prompt.get_versions()
+        version_ids = set(versions.keys())
+        existing_versions = {
+            os.path.splitext(filename)[0]
+            for filename in os.listdir(prompt_dir)
+            if filename.endswith(VERSION_FILE_EXTENSION)
+        }
+
+        # Validate that we are not overwriting existing content with new data
+        for version_id in version_ids & existing_versions:
+            version_path = os.path.join(
+                prompt_dir, f"{version_id}{VERSION_FILE_EXTENSION}"
+            )
+            with open(version_path, "r") as vf:
+                existing_content = vf.read()
+            if existing_content != versions[version_id]:
+                raise ValueError(
+                    f"Version '{version_id}' already exists with different content."
+                )
+
+        metadata: _BasePromptMetadata = {
+            "defaultVersionId": prompt.get_default_version_id(),
+            "variablesSchema": prompt.get_variables_schema(),
+        }
+        metadata_path = os.path.join(prompt_dir, "metadata.json")
+        with open(metadata_path, "w") as f:
+            json.dump(metadata, f, indent=2)
+
+        # Write only new versions; existing identical versions are left untouched
+        for version_id, content in versions.items():
+            version_path = os.path.join(
+                prompt_dir, f"{version_id}{VERSION_FILE_EXTENSION}"
+            )
+            if os.path.exists(version_path):
+                continue
+            with open(version_path, "w") as vf:
+                vf.write(content)
+
+        for stale_version in existing_versions - set(versions.keys()):
+            stale_path = os.path.join(
+                prompt_dir, f"{stale_version}{VERSION_FILE_EXTENSION}"
+            )
+            os.remove(stale_path)
+
+        version_creation_times = {
+            version_id: os.path.getctime(
+                os.path.join(prompt_dir, f"{version_id}{VERSION_FILE_EXTENSION}")
+            )
+            for version_id in versions.keys()
+        }
+
+        stored_prompt = BaseUntypedPromptWithCreationTime(
+            id=prompt_id,
+            versions=versions,
+            default_version_id=prompt.get_default_version_id(),
+            variables_schema=prompt.get_variables_schema(),
+            version_creation_times=version_creation_times,
+        )
+
+        try:
+            BasePrompt.update_prompt_registry(stored_prompt)
+        except KeyError:
+            # Prompt not in type prompt registry yet, meaning there's no usage in code
+            # thus this untyped prompt would just be stored but not used in code
+            pass
+        self._prompts[prompt_id] = stored_prompt
+        return original is None
+
+    def get(self, prompt_id: str) -> BaseUntypedPromptWithCreationTime:
+        return self._prompts[prompt_id]
+
+
+_storage_instance: PromptStorage | None = None
+
+
+# TODO allow other storage types later
+def initialize_prompt_storage(directory: str) -> None:
+    global _storage_instance
+    if _storage_instance is not None:
+        raise RuntimeError("Prompt storage has already been initialized.")
+    storage = _FilePromptStorage(directory, raise_on_error=False)
+    _storage_instance = storage
+    logger.info("Initialized prompt storage at directory: %s", directory)
+    if storage.load_failures:
+        raise PromptLoadError(storage.load_failures)
+
+
+class StorageBackedPrompt(Prompt[TPromptVar]):
+
+    def __init__(
+        self,
+        id: str,
+        *,
+        variables_definition: type[TPromptVar] = NoneType,
+    ) -> None:
+        self._id = id
+        self._variables_definition = variables_definition
+        self._prompt: BasePrompt[TPromptVar] | None = None
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @property
+    def variables_definition(self) -> type[TPromptVar]:
+        return self._variables_definition
+
+    def get_variables_schema(self) -> dict[str, Any]:
+        return variables_definition_to_schema(self._variables_definition)
+
+    def _get_prompt(self) -> BasePrompt[TPromptVar]:
+        if _storage_instance is None:
+            raise RuntimeError("Prompt storage has not been initialized.")
+        if self._prompt is None:
+            untyped_prompt = _storage_instance.get(self.id)
+            self._prompt = BasePrompt.from_untyped(
+                untyped_prompt,
+                variables_definition=self.variables_definition,
+            )
+            schema_from_storage = untyped_prompt.get_variables_schema()
+            schema_from_definition = self.get_variables_schema()
+            if not isSubschema(schema_from_definition, schema_from_storage):
+                raise TypeError(
+                    "Schema from definition is not a subschema of the schema from storage."
+                )
+        return self._prompt
+
+    def actualize(self) -> Self:
+        self._get_prompt()
+        return self
+
+    def exists_in_storage(self) -> bool:
+        if _storage_instance is None:
+            raise RuntimeError("Prompt storage has not been initialized.")
+        try:
+            self.actualize()
+            return True
+        except KeyError:
+            return False
+
+    def get_versions(self) -> dict[str, str]:
+        prompt = self._get_prompt()
+        return prompt.get_versions()
+
+    def get_version_creation_time(self, version_id: str) -> float:
+        if _storage_instance is None:
+            raise RuntimeError("Prompt storage has not been initialized.")
+        prompt_with_ctime = _storage_instance.get(self.id)
+        if not prompt_with_ctime:
+            raise KeyError(f"Prompt with id '{self.id}' not found in storage.")
+        return prompt_with_ctime.get_version_creation_time(version_id)
+
+    def get_version_count(self) -> int:
+        try:
+            prompt = self._get_prompt()
+            versions_dict = prompt.get_versions()
+            return len(versions_dict)
+        except KeyError:
+            return 0
+
+    def get_default_version_id(self) -> str:
+        prompt = self._get_prompt()
+        return prompt.get_default_version_id()
+
+    def compile(
+        self,
+        variables: TPromptVar = None,
+        *,
+        version_id: str | None = None,
+    ) -> str:
+        prompt = self._get_prompt()
+        return prompt.compile(variables=variables, version_id=version_id)
+
+    def append_version(
+        self,
+        version_id: str,
+        content: str,
+        set_as_default: bool = False,
+    ) -> BasePrompt[TPromptVar]:
+        if _storage_instance is None:
+            raise RuntimeError("Prompt storage has not been initialized.")
+        if self.exists_in_storage():
+            prompt = self._get_prompt()
+            prompt.append_version(
+                version_id=version_id,
+                content=content,
+                set_as_default=set_as_default,
+            )
+            _storage_instance.save(prompt)
+            return prompt
+        else:
+            # it should be safe to assume there's no actualized prompt for this id
+            # thus it should be same to create a new instance of BasePrompt
+            new_prompt = BasePrompt(
+                id=self.id,
+                versions={version_id: content},
+                variables_definition=self.variables_definition,
+                default_version_id=version_id,
+            )
+            _storage_instance.save(new_prompt)
+            return new_prompt
+
+    def update_default_version_id(
+        self,
+        version_id: str,
+    ) -> BasePrompt[TPromptVar]:
+        if _storage_instance is None:
+            raise RuntimeError("Prompt storage has not been initialized.")
+        prompt = self._get_prompt()
+        prompt.update_default_version_id(version_id)
+        _storage_instance.save(prompt)
+        return prompt

pixie_prompts-0.1.1.dist-info/METADATA

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: pixie-prompts
+Version: 0.1.1
+Summary: Code-first, type-safe prompt management
+License: MIT
+License-File: LICENSE
+Author: Yiou Li
+Author-email: yol@gopixie.ai
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: server
+Requires-Dist: colorlog (>=6.10.1) ; extra == "server"
+Requires-Dist: dotenv (>=0.9.9) ; extra == "server"
+Requires-Dist: fastapi (>=0.128.0) ; extra == "server"
+Requires-Dist: jinja2 (>=3.1.6,<4.0.0)
+Requires-Dist: jsonsubschema (>=0.0.7,<0.0.8)
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)
+Requires-Dist: strawberry-graphql (>=0.288.1) ; extra == "server"
+Requires-Dist: uvicorn (>=0.40.0) ; extra == "server"
+Requires-Dist: watchdog (>=6.0.0) ; extra == "server"
+Project-URL: Changelog, https://github.com/yiouli/pixie-prompts/commits/main/
+Project-URL: Documentation, https://yiouli.github.io/pixie-prompts/
+Project-URL: Homepage, https://gopixie.ai
+Project-URL: Issues, https://github.com/yiouli/pixie-prompts/issues
+Project-URL: Repository, https://github.com/yiouli/pixie-prompts
+Description-Content-Type: text/markdown
+
+# pixie-prompts
+Code-first, type-checked prompt management.
+

pixie_prompts-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+pixie/prompts/__init__.py,sha256=ZueU9cJ7aiVHBQYH4g3MXAFtjQwTfvvpy3d8ZTtBQ2c,396
+pixie/prompts/file_watcher.py,sha256=F-p84r820en6qb3vNjJleWyUp4AR2UC7ZCGvWNJq0sM,10530
+pixie/prompts/graphql.py,sha256=5pouvFlKdZxJYxxd2cRvxHBCmvpc5JEAReflPYfzqko,6548
+pixie/prompts/prompt.py,sha256=7nBn1PCXNOVL6OflHak7MG9rlZ4Ooa14eTamYk2mE3I,11472
+pixie/prompts/prompt_management.py,sha256=gq5Eklqy2_Sq8jATVae4eANNmyFE8s8a9cedxWs2P_Y,2816
+pixie/prompts/server.py,sha256=_BsPfE_VJTvqNOaJPf14LXT-ubYRWbNi1NPFvAgXi5s,6433
+pixie/prompts/storage.py,sha256=syVHO5IWZXtN20ozPoBq_Anbu0NAH056EWbvlNNWLGU,14448
+pixie_prompts-0.1.1.dist-info/METADATA,sha256=2rG-8DTU6Y9aXGYM3PwrK74wwG1Y9rCaBT0HsCSN9MA,1478
+pixie_prompts-0.1.1.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
+pixie_prompts-0.1.1.dist-info/entry_points.txt,sha256=SWOSFuUXDxkJMmf28u7E0Go_LcEpofz7NAlV70Cp8Es,48
+pixie_prompts-0.1.1.dist-info/licenses/LICENSE,sha256=nZoehBpdSXe6iTF2ZWzM-fgXdXECUZ0J8LrW_1tBwyk,1064
+pixie_prompts-0.1.1.dist-info/RECORD,,

pixie_prompts-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pixie_prompts-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pp=pixie.prompts.server:main
+

pixie_prompts-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yiou Li
+
+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.