textprompts 0.0.1__py3-none-any.whl

textprompts/__init__.py

@@ -0,0 +1,29 @@
+from .config import MetadataMode, get_metadata, set_metadata
+from .errors import (
+    FileMissingError,
+    InvalidMetadataError,
+    MalformedHeaderError,
+    MissingMetadataError,
+    TextPromptsError,
+)
+from .loaders import load_prompt, load_prompts
+from .models import Prompt, PromptMeta
+from .safe_string import SafeString
+from .savers import save_prompt
+
+__all__ = [
+    "load_prompt",
+    "load_prompts",
+    "save_prompt",
+    "Prompt",
+    "PromptMeta",
+    "SafeString",
+    "MetadataMode",
+    "set_metadata",
+    "get_metadata",
+    "TextPromptsError",
+    "FileMissingError",
+    "MissingMetadataError",
+    "InvalidMetadataError",
+    "MalformedHeaderError",
+]

textprompts/_parser.py

@@ -0,0 +1,139 @@
+import textwrap
+from pathlib import Path
+from typing import Optional
+
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib  # type: ignore[import-not-found, no-redef]
+
+from .config import MetadataMode
+from .errors import InvalidMetadataError, MalformedHeaderError, MissingMetadataError
+from .models import Prompt, PromptMeta
+from .safe_string import SafeString
+
+DELIM = "---"
+
+
+def _split_front_matter(text: str) -> tuple[Optional[str], str]:
+    """
+    Returns (header, body). Header may be None.
+
+    Strict parsing: only considers "---" at the very beginning of the file
+    (no leading whitespace) as valid front matter delimiter.
+    """
+    # Must start exactly with "---" (no leading whitespace)
+    if not text.startswith(DELIM):
+        return None, text
+
+    # Find second delimiter after the first
+    second_delim = text.find(DELIM, len(DELIM))
+    if second_delim == -1:
+        raise MalformedHeaderError("Missing closing delimiter '---' for front matter")
+
+    # Extract header and body
+    header = text[len(DELIM) : second_delim].strip()
+    body = text[second_delim + len(DELIM) :].lstrip("\n")
+
+    return header, body
+
+
+def parse_file(path: Path, *, metadata_mode: MetadataMode) -> Prompt:
+    """
+    Parse a file according to the specified metadata mode.
+
+    Parameters
+    ----------
+    path : Path
+        The file to parse.
+    metadata_mode : MetadataMode
+        The metadata handling mode.
+    """
+
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as e:
+        from .errors import TextPromptsError
+
+        raise TextPromptsError(f"Cannot decode {path} as UTF-8: {e}") from e
+
+    # Handle IGNORE mode - treat entire file as body
+    if metadata_mode == MetadataMode.IGNORE:
+        ignore_meta = PromptMeta(title=path.stem)
+        return Prompt(path=path, meta=ignore_meta, body=SafeString(textwrap.dedent(raw)))
+
+    # For STRICT and ALLOW modes, try to parse front matter
+    try:
+        header_txt, body = _split_front_matter(raw)
+    except MalformedHeaderError as e:
+        # If parsing fails and file starts with "---", suggest using IGNORE mode
+        if raw.startswith(DELIM):
+            raise InvalidMetadataError(
+                f"{e}. If this file has no metadata and starts with '---', "
+                f"use meta=MetadataMode.IGNORE to skip metadata parsing."
+            ) from e
+        raise
+
+    meta: Optional[PromptMeta] = None
+    if header_txt is not None:
+        # We have front matter - parse it
+        try:
+            data = tomllib.loads(header_txt)
+
+            if metadata_mode == MetadataMode.STRICT:
+                # STRICT mode: require title, description, version fields and they must not be empty
+                required_fields = {"title", "description", "version"}
+                missing_fields = required_fields - set(data.keys())
+                if missing_fields:
+                    raise InvalidMetadataError(
+                        f"Missing required metadata fields: {', '.join(sorted(missing_fields))}. "
+                        f"STRICT mode requires 'title', 'description', and 'version' fields. "
+                        f"Use meta=MetadataMode.ALLOW for less strict validation."
+                    )
+
+                # Check for empty required fields
+                empty_fields = [
+                    field
+                    for field in required_fields
+                    if not data.get(field) or str(data.get(field)).strip() == ""
+                ]
+                if empty_fields:
+                    raise InvalidMetadataError(
+                        f"Empty required metadata fields: {', '.join(sorted(empty_fields))}. "
+                        f"STRICT mode requires non-empty 'title', 'description', and 'version' fields. "
+                        f"Use meta=MetadataMode.ALLOW for less strict validation."
+                    )
+
+            # For both STRICT and ALLOW modes, validate the data structure
+            meta = PromptMeta.model_validate(data)
+
+        except tomllib.TOMLDecodeError as e:
+            raise InvalidMetadataError(
+                f"Invalid TOML in front matter: {e}. "
+                f"Use meta=MetadataMode.IGNORE to skip metadata parsing."
+            ) from e
+        except InvalidMetadataError:
+            raise
+        except Exception as e:
+            raise InvalidMetadataError(f"Invalid metadata: {e}") from e
+
+    else:
+        # No front matter found
+        if metadata_mode == MetadataMode.STRICT:
+            raise MissingMetadataError(
+                f"No metadata found in {path}. "
+                f"STRICT mode requires metadata with title, description, and version fields. "
+                f"Use meta=MetadataMode.ALLOW or meta=MetadataMode.IGNORE for less strict validation."
+            )
+        # ALLOW mode: create empty metadata
+        meta = PromptMeta()
+
+    # Always ensure we have metadata with a title
+    if not meta:
+        meta = PromptMeta()
+
+    # Use filename as title if not provided
+    if meta.title is None:
+        meta.title = path.stem
+
+    return Prompt(path=path, meta=meta, body=SafeString(textwrap.dedent(body)))

textprompts/cli.py

@@ -0,0 +1,31 @@
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .errors import TextPromptsError
+from .loaders import load_prompt
+
+
+def _make_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(description="Show prompt metadata/body")
+    p.add_argument("file", type=Path)
+    p.add_argument("--json", action="store_true", help="Print metadata as JSON")
+    return p
+
+
+def main() -> None:
+    args = _make_parser().parse_args()
+    try:
+        prompt = load_prompt(args.file, meta="ignore")
+        if args.json:
+            print(json.dumps(prompt.meta.model_dump() if prompt.meta else {}, indent=2))
+        else:
+            print(prompt.body)
+    except TextPromptsError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

textprompts/config.py

@@ -0,0 +1,110 @@
+"""
+Global configuration for textprompts metadata handling.
+"""
+
+from enum import Enum
+from typing import Union
+
+
+class MetadataMode(Enum):
+    """
+    Metadata handling modes for prompt loading.
+
+    Attributes
+    ----------
+    STRICT : MetadataMode
+        Requires metadata with title, description, version fields that are not empty.
+        Throws error if metadata is missing or any required field is empty.
+    ALLOW : MetadataMode
+        Loads any metadata that exists, fields can be empty or None.
+        Only throws error if TOML syntax is invalid.
+    IGNORE : MetadataMode
+        Doesn't parse metadata at all, treats entire file as prompt body.
+        Uses filename (without extension) as title.
+    """
+
+    STRICT = "strict"
+    ALLOW = "allow"
+    IGNORE = "ignore"
+
+
+# Global configuration variable
+_METADATA_MODE: MetadataMode = MetadataMode.IGNORE
+
+
+def set_metadata(mode: Union[MetadataMode, str]) -> None:
+    """
+    Set the global metadata handling mode.
+
+    Parameters
+    ----------
+    mode : MetadataMode or str
+        The metadata handling mode to use globally.
+        Can be MetadataMode enum or string: "strict", "allow", or "ignore".
+
+    Examples
+    --------
+    >>> import textprompts
+    >>> textprompts.set_metadata(textprompts.MetadataMode.STRICT)
+    >>> textprompts.set_metadata("allow")  # Also works with strings
+
+    Raises
+    ------
+    ValueError
+        If mode is not a valid MetadataMode or string.
+    """
+    global _METADATA_MODE
+
+    if isinstance(mode, str):
+        try:
+            mode = MetadataMode(mode.lower())
+        except ValueError:
+            valid_modes = [m.value for m in MetadataMode]
+            raise ValueError(
+                f"Invalid metadata mode: {mode}. Valid modes: {valid_modes}"
+            )
+
+    if not isinstance(mode, MetadataMode):
+        raise ValueError(f"Mode must be MetadataMode enum or string, got {type(mode)}")
+
+    _METADATA_MODE = mode
+
+
+def get_metadata() -> MetadataMode:
+    """
+    Get the current global metadata handling mode.
+
+    Returns
+    -------
+    MetadataMode
+        The current global metadata handling mode.
+    """
+    return _METADATA_MODE
+
+
+def _resolve_metadata_mode(meta: Union[MetadataMode, str, None]) -> MetadataMode:
+    """
+    Resolve the metadata mode from parameters and global config.
+
+    Priority order:
+    1. meta parameter (if provided)
+    2. global configuration
+
+    Parameters
+    ----------
+    meta : MetadataMode, str, or None
+        Explicit metadata mode override.
+
+    Returns
+    -------
+    MetadataMode
+        The resolved metadata mode to use.
+    """
+    # Priority 1: explicit meta parameter
+    if meta is not None:
+        if isinstance(meta, str):
+            return MetadataMode(meta.lower())
+        return meta
+
+    # Priority 2: global configuration
+    return _METADATA_MODE

textprompts/errors.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+
+
+class TextPromptsError(Exception): ...
+
+
+class FileMissingError(TextPromptsError):
+    def __init__(self, path: Path):
+        super().__init__(f"File not found: {path}")
+
+
+class MissingMetadataError(TextPromptsError): ...
+
+
+class InvalidMetadataError(TextPromptsError): ...
+
+
+class MalformedHeaderError(TextPromptsError): ...

textprompts/loaders.py

@@ -0,0 +1,113 @@
+from pathlib import Path
+from typing import Iterable, Union
+
+from ._parser import parse_file
+from .config import MetadataMode, _resolve_metadata_mode
+from .errors import FileMissingError
+from .models import Prompt
+
+
+def load_prompt(
+    path: Union[str, Path], *, meta: Union[MetadataMode, str, None] = None
+) -> Prompt:
+    """
+    Load a single prompt file.
+
+    Parameters
+    ----------
+    path : str | Path
+        File to load.
+    meta : MetadataMode, str, or None, default None
+        Metadata handling mode. Can be:
+        - MetadataMode.STRICT: Requires metadata with title, description, version (not empty)
+        - MetadataMode.ALLOW: Loads any metadata, can be empty, only errors on TOML parse failure
+        - MetadataMode.IGNORE: No metadata parsing, uses filename as title
+        - String: "strict", "allow", or "ignore"
+        - None: Use global configuration
+
+    Raises
+    ------
+    TextPromptsError subclasses on any failure.
+
+    Examples
+    --------
+    >>> # Using global configuration
+    >>> import textprompts
+    >>> textprompts.set_metadata(textprompts.MetadataMode.STRICT)
+    >>> prompt = textprompts.load_prompt("example.txt")
+
+    >>> # Override with parameter
+    >>> prompt = textprompts.load_prompt("example.txt", meta=textprompts.MetadataMode.ALLOW)
+    >>> prompt = textprompts.load_prompt("example.txt", meta="ignore")  # String also works
+    """
+    fp = Path(path)
+    if not fp.is_file():
+        raise FileMissingError(fp)
+
+    # Resolve metadata mode from parameters and global config
+    mode = _resolve_metadata_mode(meta)
+
+    return parse_file(fp, metadata_mode=mode)
+
+
+def load_prompts(
+    *paths: Union[str, Path],
+    recursive: bool = False,
+    glob: str = "*.txt",
+    meta: Union[MetadataMode, str, None] = None,
+    max_files: Union[int, None] = 1000,
+) -> list[Prompt]:
+    """
+    Convenience loader for many files / directories.
+
+    Parameters
+    ----------
+    *paths : str | Path
+        Files and directories to load.
+    recursive : bool, default False
+        If True, search directories recursively.
+    glob : str, default "*.txt"
+        Glob pattern for finding files in directories.
+    meta : MetadataMode, str, or None, default None
+        Metadata handling mode. Can be:
+        - MetadataMode.STRICT: Requires metadata with title, description, version (not empty)
+        - MetadataMode.ALLOW: Loads any metadata, can be empty, only errors on TOML parse failure
+        - MetadataMode.IGNORE: No metadata parsing, uses filename as title
+        - String: "strict", "allow", or "ignore"
+        - None: Use global configuration
+    max_files : int | None, default 1000
+        Maximum number of files to process. None for no limit.
+
+    Examples
+    --------
+    >>> # Using global configuration
+    >>> import textprompts
+    >>> textprompts.set_metadata(textprompts.MetadataMode.ALLOW)
+    >>> prompts = textprompts.load_prompts("prompts/", recursive=True)
+
+    >>> # Override with parameter
+    >>> prompts = textprompts.load_prompts("prompts/", meta="strict")
+    """
+    collected: list[Prompt] = []
+    file_count = 0
+
+    for p in paths:
+        pth = Path(p)
+        if pth.is_dir():
+            itr: Iterable[Path] = pth.rglob(glob) if recursive else pth.glob(glob)
+            for f in itr:
+                if max_files and file_count >= max_files:
+                    from .errors import TextPromptsError
+
+                    raise TextPromptsError(f"Exceeded max_files limit of {max_files}")
+                collected.append(load_prompt(f, meta=meta))
+                file_count += 1
+        else:
+            if max_files and file_count >= max_files:
+                from .errors import TextPromptsError
+
+                raise TextPromptsError(f"Exceeded max_files limit of {max_files}")
+            collected.append(load_prompt(pth, meta=meta))
+            file_count += 1
+
+    return collected

textprompts/models.py

@@ -0,0 +1,42 @@
+from datetime import date
+from pathlib import Path
+from typing import Union
+
+from pydantic import BaseModel, Field, field_validator
+
+from .safe_string import SafeString
+
+
+class PromptMeta(BaseModel):
+    title: Union[str, None] = Field(default=None, description="Human-readable name")
+    version: Union[str, None] = Field(default=None)
+    author: Union[str, None] = Field(default=None)
+    created: Union[date, None] = Field(default=None)
+    description: Union[str, None] = Field(default=None)
+
+
+class Prompt(BaseModel):
+    path: Path
+    meta: Union[PromptMeta, None]
+    body: SafeString
+
+    @field_validator("body")
+    @classmethod
+    def body_not_empty(cls, v: str) -> SafeString:
+        if not v.strip():
+            raise ValueError("Prompt body is empty")
+        return SafeString(v)
+
+    def __repr__(self) -> str:
+        if self.meta and self.meta.title:
+            if self.meta.version:
+                return (
+                    f"Prompt(title='{self.meta.title}', version='{self.meta.version}')"
+                )
+            else:
+                return f"Prompt(title='{self.meta.title}')"
+        else:
+            return f"Prompt(path='{self.path}')"
+
+    def __str__(self) -> str:
+        return str(self.body)

textprompts/placeholder_utils.py

@@ -0,0 +1,138 @@
+"""
+Utility functions for extracting and validating placeholders in format strings.
+
+This module provides robust placeholder extraction and validation for SafeString
+formatting operations.
+"""
+
+import re
+from typing import Any, Dict, Set, Tuple
+
+
+def extract_placeholders(text: str) -> Set[str]:
+    """
+    Extract all placeholder names from a format string.
+
+    Handles various placeholder formats including:
+    - Named placeholders: {name}
+    - Positional placeholders: {0}, {1}
+    - Format specifiers: {value:02d}, {price:.2f}
+    - Ignores escaped braces: {{literal}}
+
+    Args:
+        text: The format string to extract placeholders from
+
+    Returns:
+        Set of placeholder names found in the string
+
+    Examples:
+        >>> extract_placeholders("Hello {name}!")
+        {'name'}
+        >>> extract_placeholders("Item {0}: {name} costs ${price:.2f}")
+        {'0', 'name', 'price'}
+        >>> extract_placeholders("No placeholders here")
+        set()
+        >>> extract_placeholders("Escaped {{braces}} but {real} placeholder")
+        {'real'}
+    """
+    # Replace escaped braces with temporary markers to avoid matching them
+    temp_text = text.replace("{{", "\x00ESCAPED_OPEN\x00").replace(
+        "}}", "\x00ESCAPED_CLOSE\x00"
+    )
+
+    # Find all placeholder patterns: {name}, {0}, {value:format}, {}
+    # Pattern explanation:
+    # \{           - literal opening brace
+    # ([^}:]*)     - capture group 1: placeholder name (can be empty, stops at : or })
+    # (?::[^}]*)?  - optional format specifier (non-capturing group)
+    # \}           - literal closing brace
+    pattern = r"\{([^}:]*)(?::[^}]*)?\}"
+
+    matches = re.findall(pattern, temp_text)
+    return set(matches)
+
+
+def validate_format_args(
+    placeholders: Set[str], args: Tuple[Any, ...], kwargs: Dict[str, Any], skip_validation: bool = False
+) -> None:
+    """
+    Validate that format arguments match the placeholders in the template.
+
+    Args:
+        placeholders: Set of placeholder names expected in the template
+        args: Positional arguments passed to format()
+        kwargs: Keyword arguments passed to format()
+        skip_validation: If True, skip all validation checks
+
+    Raises:
+        ValueError: If there are missing placeholders or validation fails
+
+    Examples:
+        >>> validate_format_args({'name'}, (), {'name': 'Alice'})  # OK
+        >>> validate_format_args({'name'}, (), {})  # Raises ValueError
+        >>> validate_format_args({'name'}, (), {}, skip_validation=True)  # OK
+    """
+    if skip_validation:
+        return
+
+    # Convert positional args to keyword args using string indices
+    all_kwargs = kwargs.copy()
+    for i, arg in enumerate(args):
+        all_kwargs[str(i)] = arg
+
+    # Special handling for empty placeholders - they match positional args
+    # If we have an empty placeholder and positional args, match them
+    if "" in placeholders and args:
+        all_kwargs[""] = args[0]
+
+    # Check for missing placeholders
+    provided_keys = set(str(k) for k in all_kwargs.keys())
+    missing_keys = placeholders - provided_keys
+
+    if missing_keys:
+        raise ValueError(f"Missing format variables: {sorted(missing_keys)}")
+
+
+def should_ignore_validation(ignore_flag: bool) -> bool:
+    """
+    Determine if placeholder validation should be ignored.
+
+    This is a simple utility function that could be extended in the future
+    to handle more complex validation logic or global settings.
+
+    Args:
+        ignore_flag: The _ignore_placeholders flag value
+
+    Returns:
+        True if validation should be bypassed, False otherwise
+    """
+    return ignore_flag
+
+
+def get_placeholder_info(text: str) -> Dict[str, Any]:
+    """
+    Get detailed information about placeholders in a format string.
+
+    Args:
+        text: The format string to analyze
+
+    Returns:
+        Dictionary with placeholder analysis information
+
+    Examples:
+        >>> info = get_placeholder_info("Hello {name}, you have {count:d} items")
+        >>> info['count']
+        2
+        >>> info['names']
+        {'name', 'count'}
+    """
+    placeholders = extract_placeholders(text)
+
+    return {
+        "count": len(placeholders),
+        "names": placeholders,
+        "has_positional": any(p.isdigit() for p in placeholders),
+        "has_named": any(not p.isdigit() for p in placeholders),
+        "is_mixed": any(p.isdigit() for p in placeholders)
+        and any(not p.isdigit() for p in placeholders),
+    }

textprompts/safe_string.py

@@ -0,0 +1,110 @@
+from typing import Any, Set
+
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import core_schema
+
+from .placeholder_utils import extract_placeholders, validate_format_args
+
+
+class SafeString(str):
+    """
+    A string subclass that validates format() calls to ensure all placeholders are provided.
+
+    This prevents common errors where format variables are missing, making prompt templates
+    more reliable and easier to debug.
+
+    Attributes:
+        placeholders: Set of placeholder names found in the string
+    """
+
+    placeholders: Set[str]
+
+    def __new__(cls, value: str) -> "SafeString":
+        """Create a new SafeString instance with extracted placeholders."""
+        instance = str.__new__(cls, value)
+        instance.placeholders = extract_placeholders(value)
+        return instance
+
+    def format(self, *args: Any, **kwargs: Any) -> str:
+        """
+        Format the string with configurable validation behavior.
+
+        By default (skip_validation=False), this method validates that all placeholders
+        have corresponding values and raises ValueError if any are missing.
+
+        When skip_validation=True, it performs partial formatting, replacing only
+        the placeholders for which values are provided.
+
+        Args:
+            *args: Positional arguments for formatting
+            skip_validation: If True, perform partial formatting without validation
+            **kwargs: Keyword arguments for formatting
+
+        Returns:
+            The formatted string
+
+        Raises:
+            ValueError: If skip_validation=False and any placeholder is missing
+        """
+        skip_validation = kwargs.pop('skip_validation', False)
+        if skip_validation:
+            # Partial formatting - replace only available placeholders
+            return self._partial_format(*args, **kwargs)
+        else:
+            # Strict formatting - validate all placeholders are provided
+            validate_format_args(self.placeholders, args, kwargs, skip_validation=False)
+            return str.format(self, *args, **kwargs)
+
+    def _partial_format(self, *args: Any, **kwargs: Any) -> str:
+        """
+        Perform partial formatting, replacing only the placeholders that have values.
+
+        Args:
+            *args: Positional arguments for formatting
+            **kwargs: Keyword arguments for formatting
+
+        Returns:
+            The partially formatted string
+        """
+        # Convert positional args to keyword args
+        all_kwargs = kwargs.copy()
+        for i, arg in enumerate(args):
+            all_kwargs[str(i)] = arg
+
+        # Build a format string with only available placeholders
+        result = str(self)
+
+        # Replace placeholders one by one if they have values
+        for placeholder in self.placeholders:
+            if placeholder in all_kwargs:
+                # Create a single-placeholder format string
+                placeholder_pattern = f"{{{placeholder}}}"
+                if placeholder_pattern in result:
+                    try:
+                        # Replace this specific placeholder
+                        result = result.replace(
+                            placeholder_pattern, str(all_kwargs[placeholder])
+                        )
+                    except (KeyError, ValueError):
+                        # If replacement fails, leave the placeholder as is
+                        pass
+
+        return result
+
+    def __str__(self) -> str:
+        """Return the string representation."""
+        return str.__str__(self)
+
+    def __repr__(self) -> str:
+        """Return the string representation for debugging."""
+        return f"SafeString({str.__repr__(self)}, placeholders={self.placeholders})"
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source_type: Any, handler: GetCoreSchemaHandler
+    ) -> core_schema.CoreSchema:
+        """Support for Pydantic v2 schema generation."""
+        return core_schema.no_info_after_validator_function(
+            cls,
+            core_schema.str_schema(),
+        )

textprompts/savers.py

@@ -0,0 +1,66 @@
+from pathlib import Path
+from typing import Union
+
+from .models import Prompt, PromptMeta
+
+
+def save_prompt(path: Union[str, Path], content: Union[str, Prompt]) -> None:
+    """
+    Save a prompt to a file.
+
+    Parameters
+    ----------
+    path : str | Path
+        File path to save the prompt to.
+    content : str | Prompt
+        Either a string (prompt text only) or a Prompt object with metadata.
+        If a string is provided, a template with required metadata fields will be created.
+
+    Examples
+    --------
+    >>> # Save a simple prompt with metadata template
+    >>> save_prompt("my_prompt.txt", "You are a helpful assistant.")
+
+    >>> # Save a Prompt object with full metadata
+    >>> prompt = Prompt(
+    ...     path=Path("my_prompt.txt"),
+    ...     meta=PromptMeta(title="Assistant", version="1.0.0", description="A helpful AI"),
+    ...     body="You are a helpful assistant."
+    ... )
+    >>> save_prompt("my_prompt.txt", prompt)
+    """
+    path = Path(path)
+
+    if isinstance(content, str):
+        # Create template with required fields
+        template = f"""---
+title = ""
+description = ""
+version = ""
+---
+
+{content}"""
+        path.write_text(template, encoding="utf-8")
+    elif isinstance(content, Prompt):
+        # Build the front matter
+        lines = ["---"]
+
+        # Always include required fields
+        meta = content.meta or PromptMeta()
+        lines.append(f'title = "{meta.title or ""}"')
+        lines.append(f'description = "{meta.description or ""}"')
+        lines.append(f'version = "{meta.version or ""}"')
+
+        # Include optional fields if present
+        if meta.author:
+            lines.append(f'author = "{meta.author}"')
+        if meta.created:
+            lines.append(f'created = "{meta.created.isoformat()}"')
+
+        lines.append("---")
+        lines.append("")
+        lines.append(str(content.body))
+
+        path.write_text("\n".join(lines), encoding="utf-8")
+    else:
+        raise TypeError(f"content must be str or Prompt, not {type(content).__name__}")

textprompts-0.0.1.dist-info/METADATA

@@ -0,0 +1,493 @@
+Metadata-Version: 2.4
+Name: textprompts
+Version: 0.0.1
+Summary: Minimal text-based prompt-loader with TOML front-matter
+Keywords: prompts,toml,frontmatter,template
+Author: Jan Siml
+Author-email: Jan Siml <49557684+svilupp@users.noreply.github.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: pydantic~=2.7
+Requires-Dist: tomli>=1.0.0 ; python_full_version < '3.11'
+Requires-Python: >=3.11
+Project-URL: Bug Tracker, https://github.com/svilupp/textprompts/issues
+Project-URL: Documentation, https://github.com/svilupp/textprompts#readme
+Project-URL: Homepage, https://github.com/svilupp/textprompts
+Description-Content-Type: text/markdown
+
+# textprompts
+
+> **So simple, it's not even worth vibing about coding yet it just makes so much sense.**
+
+Are you tired of vendors trying to sell you fancy UIs for prompt management that just make your system more confusing and harder to debug? Isn't it nice to just have your prompts **next to your code**? 
+
+But then you worry: *Did my formatter change my prompt? Are those spaces at the beginning actually part of the prompt or just indentation?*
+
+**textprompts** solves this elegantly: treat your prompts as **text files** and keep your linters and formatters away from them.
+
+## Why textprompts?
+
+- ✅ **Prompts live next to your code** - no external systems to manage
+- ✅ **Git is your version control** - diff, branch, and experiment with ease  
+- ✅ **No formatter headaches** - your prompts stay exactly as you wrote them
+- ✅ **Minimal markup** - just TOML front-matter when you need metadata (or no metadata if you prefer!)
+- ✅ **Zero dependencies** - well, almost (just Pydantic)
+- ✅ **Safe formatting** - catch missing variables before they cause problems
+- ✅ **Works with everything** - OpenAI, Anthropic, local models, function calls
+
+## Installation
+
+```bash
+uv add textprompts # or pip install textprompts
+```
+
+## Quick Start
+
+**Super simple by default** - TextPrompts just loads text files with optional metadata:
+
+1. **Create a prompt file** (`greeting.txt`):
+```
+---
+title = "Customer Greeting"
+version = "1.0.0"
+description = "Friendly greeting for customer support"
+---
+
+Hello {customer_name}!
+
+Welcome to {company_name}. We're here to help you with {issue_type}.
+
+Best regards,
+{agent_name}
+```
+
+2. **Load and use it** (no configuration needed):
+```python
+import textprompts
+
+# Just load it - works with or without metadata
+prompt = textprompts.load_prompt("greeting.txt")
+
+# Use it safely - all placeholders must be provided
+message = prompt.body.format(
+    customer_name="Alice",
+    company_name="ACME Corp", 
+    issue_type="billing question",
+    agent_name="Sarah"
+)
+
+print(message)
+
+# Or use partial formatting when needed
+partial = prompt.body.format(
+    customer_name="Alice",
+    company_name="ACME Corp",
+    skip_validation=True
+)
+# Result: "Hello Alice!\n\nWelcome to ACME Corp. We're here to help you with {issue_type}.\n\nBest regards,\n{agent_name}"
+```
+
+**Even simpler** - no metadata required:
+```python
+# simple_prompt.txt contains just: "Analyze this data: {data}"
+prompt = textprompts.load_prompt("simple_prompt.txt")  # Just works!
+result = prompt.body.format(data="sales figures")
+```
+
+## Core Features
+
+### Safe String Formatting
+
+Never ship a prompt with missing variables again:
+
+```python
+from textprompts import SafeString
+
+template = SafeString("Hello {name}, your order {order_id} is {status}")
+
+# ✅ Strict formatting - all placeholders must be provided
+result = template.format(name="Alice", order_id="12345", status="shipped")
+
+# ❌ This catches the error by default
+try:
+    result = template.format(name="Alice")  # Missing order_id and status
+except ValueError as e:
+    print(f"Error: {e}")  # Missing format variables: ['order_id', 'status']
+
+# ✅ Partial formatting - replace only what you have
+partial = template.format(name="Alice", skip_validation=True)
+print(partial)  # "Hello Alice, your order {order_id} is {status}"
+```
+
+### Bulk Loading
+
+Load entire directories of prompts:
+
+```python
+from textprompts import load_prompts
+
+# Load all prompts from a directory
+prompts = load_prompts("prompts/", recursive=True)
+
+# Create a lookup
+prompt_dict = {p.meta.title: p for p in prompts if p.meta}
+greeting = prompt_dict["Customer Greeting"]
+```
+
+### Simple & Flexible Metadata Handling
+
+TextPrompts is designed to be **super simple** by default - just load text files with optional metadata when available. No configuration needed!
+
+```python
+import textprompts
+
+# Default behavior: load metadata if available, otherwise just use the file content
+prompt = textprompts.load_prompt("my_prompt.txt")  # Just works!
+
+# Three modes available for different use cases:
+# 1. IGNORE (default): Treat as simple text file, use filename as title
+textprompts.set_metadata("ignore")  # Super simple file loading
+prompt = textprompts.load_prompt("prompt.txt")  # No metadata parsing
+print(prompt.meta.title)  # "prompt" (from filename)
+
+# 2. ALLOW: Load metadata if present, don't worry if it's incomplete
+textprompts.set_metadata("allow")  # Flexible metadata loading  
+prompt = textprompts.load_prompt("prompt.txt")  # Loads any metadata found
+
+# 3. STRICT: Require complete metadata for production use
+textprompts.set_metadata("strict")  # Prevent errors in production
+prompt = textprompts.load_prompt("prompt.txt")  # Must have title, description, version
+
+# Override per prompt when needed
+prompt = textprompts.load_prompt("prompt.txt", meta="strict")
+```
+
+**Why this design?**
+- **Default = Simple**: No configuration needed, just load files
+- **Flexible**: Add metadata when you want structure  
+- **Production-Safe**: Use strict mode to catch missing metadata before deployment
+
+## Real-World Examples
+
+### OpenAI Integration
+
+```python
+import openai
+from textprompts import load_prompt
+
+system_prompt = load_prompt("prompts/customer_support_system.txt")
+user_prompt = load_prompt("prompts/user_query_template.txt")
+
+response = openai.chat.completions.create(
+    model="gpt-4.1-mini",
+    messages=[
+        {
+            "role": "system",
+            "content": system_prompt.body.format(
+                company_name="ACME Corp",
+                support_level="premium"
+            )
+        },
+        {
+            "role": "user", 
+            "content": user_prompt.body.format(
+                query="How do I return an item?",
+                customer_tier="premium"
+            )
+        }
+    ]
+)
+```
+
+### Function Calling (Tool Definitions)
+
+Yes, you can version control your function schemas too:
+
+```python
+# tools/search_products.txt
+---
+title = "Product Search Tool"
+version = "2.1.0"
+description = "Search our product catalog"
+---
+
+{
+    "type": "function",
+    "function": {
+        "name": "search_products",
+        "description": "Search for products in our catalog",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Search query for products"
+                },
+                "category": {
+                    "type": "string", 
+                    "enum": ["electronics", "clothing", "books"],
+                    "description": "Product category to search within"
+                },
+                "max_results": {
+                    "type": "integer",
+                    "default": 10,
+                    "description": "Maximum number of results to return"
+                }
+            },
+            "required": ["query"]
+        }
+    }
+}
+```
+
+```python
+import json
+from textprompts import load_prompt
+
+# Load and parse the tool definition
+tool_prompt = load_prompt("tools/search_products.txt")
+tool_schema = json.loads(tool_prompt.body)
+
+# Use with OpenAI
+response = openai.chat.completions.create(
+    model="gpt-4.1-mini",
+    messages=[{"role": "user", "content": "Find me some electronics"}],
+    tools=[tool_schema]
+)
+```
+
+### Environment-Specific Prompts
+
+```python
+import os
+from textprompts import load_prompt
+
+env = os.getenv("ENVIRONMENT", "development")
+system_prompt = load_prompt(f"prompts/{env}/system.txt")
+
+# prompts/development/system.txt - verbose logging
+# prompts/production/system.txt - concise responses
+```
+
+### Prompt Versioning & Experimentation
+
+```python
+from textprompts import load_prompt
+
+# Easy A/B testing
+prompt_version = "v2"  # or "v1", "experimental", etc.
+prompt = load_prompt(f"prompts/{prompt_version}/system.txt")
+
+# Git handles the rest:
+# git checkout experiment-branch
+# git diff main -- prompts/
+```
+
+## File Format
+
+TextPrompts uses TOML front-matter (optional) followed by your prompt content:
+
+```
+---
+title = "My Prompt"
+version = "1.0.0"
+author = "Your Name"
+description = "What this prompt does"
+created = "2024-01-15"
+tags = ["customer-support", "greeting"]
+---
+
+Your prompt content goes here.
+
+Use {variables} for templating.
+```
+
+### Metadata Modes
+
+Choose the right level of strictness for your use case:
+
+1. **IGNORE** (default) - Simple text file loading, filename becomes title
+2. **ALLOW** - Load metadata if present, don't worry about completeness  
+3. **STRICT** - Require complete metadata (title, description, version) for production safety
+
+```python
+# Set globally
+textprompts.set_metadata("ignore")   # Default: simple file loading
+textprompts.set_metadata("allow")    # Flexible: load any metadata  
+textprompts.set_metadata("strict")   # Production: require complete metadata
+
+# Or override per prompt
+prompt = textprompts.load_prompt("file.txt", meta="strict")
+```
+
+## API Reference
+
+### `load_prompt(path, *, meta=None)`
+
+Load a single prompt file.
+
+- `path`: Path to the prompt file
+- `meta`: Metadata handling mode - `MetadataMode.STRICT`, `MetadataMode.ALLOW`, `MetadataMode.IGNORE`, or string equivalents. None uses global config.
+
+Returns a `Prompt` object with:
+- `prompt.meta`: Metadata from TOML front-matter (always present)
+- `prompt.body`: The prompt content as a `SafeString`
+- `prompt.path`: Path to the original file
+
+### `load_prompts(*paths, recursive=False, glob="*.txt", meta=None, max_files=1000)`
+
+Load multiple prompts from files or directories.
+
+- `*paths`: Files or directories to load
+- `recursive`: Search directories recursively (default: False)
+- `glob`: File pattern to match (default: "*.txt")
+- `meta`: Metadata handling mode - `MetadataMode.STRICT`, `MetadataMode.ALLOW`, `MetadataMode.IGNORE`, or string equivalents. None uses global config.
+- `max_files`: Maximum files to process (default: 1000)
+
+### `set_metadata(mode)` / `get_metadata()`
+
+Set or get the global metadata handling mode.
+
+- `mode`: `MetadataMode.STRICT`, `MetadataMode.ALLOW`, `MetadataMode.IGNORE`, or string equivalents
+
+```python
+import textprompts
+
+# Set global mode
+textprompts.set_metadata(textprompts.MetadataMode.STRICT)
+textprompts.set_metadata("allow")  # String also works
+
+# Get current mode
+current_mode = textprompts.get_metadata()
+```
+
+### `save_prompt(path, content)`
+
+Save a prompt to a file.
+
+- `path`: Path to save the prompt file
+- `content`: Either a string (creates template with required fields) or a `Prompt` object
+
+```python
+from textprompts import save_prompt
+
+# Save a simple prompt with metadata template
+save_prompt("my_prompt.txt", "You are a helpful assistant.")
+
+# Save a Prompt object with full metadata
+save_prompt("my_prompt.txt", prompt_object)
+```
+
+### `SafeString`
+
+A string subclass that validates `format()` calls:
+
+```python
+from textprompts import SafeString
+
+template = SafeString("Hello {name}, you are {role}")
+
+# Strict formatting (default) - all placeholders required
+result = template.format(name="Alice", role="admin")  # ✅ Works
+result = template.format(name="Alice")  # ❌ Raises ValueError
+
+# Partial formatting - replace only available placeholders  
+partial = template.format(name="Alice", skip_validation=True)  # ✅ "Hello Alice, you are {role}"
+
+# Access placeholder information
+print(template.placeholders)  # {'name', 'role'}
+```
+
+## Error Handling
+
+TextPrompts provides specific exception types:
+
+```python
+from textprompts import (
+    TextPromptsError,       # Base exception
+    FileMissingError,       # File not found
+    MissingMetadataError,   # No TOML front-matter when required
+    InvalidMetadataError,   # Invalid TOML syntax
+    MalformedHeaderError,   # Malformed front-matter structure
+    MetadataMode,           # Metadata handling mode enum
+    set_metadata,           # Set global metadata mode
+    get_metadata            # Get global metadata mode
+)
+```
+
+## CLI Tool
+
+TextPrompts includes a CLI for quick prompt inspection:
+
+```bash
+# View a single prompt
+textprompts show greeting.txt
+
+# List all prompts in a directory
+textprompts list prompts/ --recursive
+
+# Validate prompts
+textprompts validate prompts/
+```
+
+## Best Practices
+
+1. **Organize by purpose**: Group related prompts in folders
+   ```
+   prompts/
+   ├── customer-support/
+   ├── content-generation/
+   └── code-review/
+   ```
+
+2. **Use semantic versioning**: Version your prompts like code
+   ```
+   version = "1.2.0"  # major.minor.patch
+   ```
+
+3. **Document your variables**: List expected variables in descriptions
+   ```
+   description = "Requires: customer_name, issue_type, agent_name"
+   ```
+
+4. **Test your prompts**: Write unit tests for critical prompts
+   ```python
+   def test_greeting_prompt():
+       prompt = load_prompt("greeting.txt")
+       result = prompt.body.format(customer_name="Test")
+       assert "Test" in result
+   ```
+
+5. **Use environment-specific prompts**: Different prompts for dev/prod
+   ```python
+   env = os.getenv("ENV", "development")
+   prompt = load_prompt(f"prompts/{env}/system.txt")
+   ```
+
+## Why Not Just Use String Templates?
+
+You could, but then you lose:
+- **Metadata tracking** (versions, authors, descriptions)
+- **Safe formatting** (catch missing variables)
+- **Organized storage** (searchable, documentable)
+- **Version control benefits** (proper diffs, blame, history)
+- **Tooling support** (CLI, validation, testing)
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+**textprompts** - Because your prompts deserve better than being buried in code strings. 🚀

textprompts-0.0.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+textprompts/__init__.py,sha256=60050c36585fc2a0efb2a00832304f65614a9d521e95b3f1424aee3095608360,676
+textprompts/_parser.py,sha256=95f6bfd6ff904f6ce301d1b480197fd1b6167c3f8bc67756955304ef2578c644,5159
+textprompts/cli.py,sha256=3e69ba206767319db597d2c742233786c5d2f6a473a008e47e5cd42b94639b85,810
+textprompts/config.py,sha256=9f7fad3b30e5033b85ec9f54dd9afa5746157e8b788c91b7392f0dbf703611af,2846
+textprompts/errors.py,sha256=7eda4a1bdf4ee8a50b420886d2016a52923baa05a5b5a65d6f582e3e500290d2,354
+textprompts/loaders.py,sha256=d30719e53faa4c5870955e3fea5050e32e3b2381def69978256922fce6fe259b,3895
+textprompts/models.py,sha256=d200b9f90936c19c8d1c8cd1c2deead61f8459cab776e2b7555311dad87372bd,1241
+textprompts/placeholder_utils.py,sha256=7f362bbf8cf865a2812310f5b73abe7a6107b048381da7a972698751334e85b3,4461
+textprompts/py.typed,sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855,0
+textprompts/safe_string.py,sha256=55d537f3ef8b57c20e6b8442fe972a990ab55ae69bdf49200aad03819946a0f1,4048
+textprompts/savers.py,sha256=4afb10e4b1e2189eb39504349e7e6414c0d7b16e61cbb7f9332a36dad3ebbd50,2036
+textprompts-0.0.1.dist-info/WHEEL,sha256=607c46fee47e440c91332c738096ff0f5e54ca3b0818ee85462dd5172a38e793,79
+textprompts-0.0.1.dist-info/entry_points.txt,sha256=f8f14b032092a81e77431911104853b39293c983c9390aa11fe023e8bcd5c049,54
+textprompts-0.0.1.dist-info/METADATA,sha256=7ce0ad8eb5a7464379486174fb4619d12e51775236f82e047bd596e2993e3d38,14667
+textprompts-0.0.1.dist-info/RECORD,,

textprompts-0.0.1.dist-info/WHEEL

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

textprompts-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+textprompts = textprompts.cli:main
+