Skip to content

API Docs

PromptStore

promptstore.store.PromptStore

Source code in src/promptstore/store.py 
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
class PromptStore:
    def __init__(self, location: Union[str, Path], readonly: bool = False):
        """Initialize a new PromptStore.

        Args:
            location: Path to the directory where prompts will be stored
            readonly: If True, the store will be read-only
        """
        self.location = Path(location)
        self.readonly = readonly
        self.index_path = self.location / "index.json"
        self._init_storage()

    def _init_storage(self):
        """Initialize the storage directory and index."""
        self.location.mkdir(parents=True, exist_ok=True)

        if not self.index_path.exists() and not self.readonly:
            self._save_index({})

    def _load_index(self) -> Dict:
        """Load the prompt index."""
        if not self.index_path.exists():
            return {}
        with open(self.index_path, "r", encoding="utf-8") as f:
            return json.load(f)

    def _save_index(self, index: Dict):
        """Save the prompt index."""
        if self.readonly:
            raise ReadOnlyStoreError("Cannot modify a read-only prompt store")
        with open(self.index_path, "w", encoding="utf-8") as f:
            json.dump(index, f, indent=2, ensure_ascii=False)

    @classmethod
    def from_dict(cls, prompts: Dict, readonly: bool = True) -> "PromptStore":
        """Create a PromptStore from a dictionary.

        Args:
            prompts: Dictionary of prompt data
            readonly: If True, the store will be read-only

        Returns:
            PromptStore: A prompt store initialized with the given prompts
        """
        import tempfile

        temp_dir = Path(tempfile.mkdtemp())
        store = cls(temp_dir, readonly=readonly)

        with open(store.index_path, "w", encoding="utf-8") as f:
            json.dump(prompts, f, indent=2, ensure_ascii=False)

        return store

    @classmethod
    def from_file(cls, path: Union[str, Path], readonly: bool = True) -> "PromptStore":
        """Create a PromptStore from a JSON file.

        Args:
            path: Path to the JSON file containing prompts
            readonly: If True, the store will be read-only

        Returns:
            PromptStore: A prompt store initialized with the prompts from the file
        """
        path = Path(path)
        if not path.exists():
            raise FileNotFoundError(f"Prompt file not found: {path}")

        if path.is_file():
            # If it's a single JSON file
            with open(path, "r", encoding="utf-8") as f:
                prompts = json.load(f)
        else:
            # If it's a directory containing an index.json
            index_path = path / "index.json"
            if not index_path.exists():
                raise FileNotFoundError(f"No index.json found in directory: {path}")
            with open(index_path, "r", encoding="utf-8") as f:
                prompts = json.load(f)

        return cls.from_dict(prompts, readonly=readonly)

    def add(
        self,
        content: str,
        description: Optional[str] = None,
        tags: Optional[List[str]] = None,
    ) -> Prompt:
        """Add a new prompt to the store."""
        if self.readonly:
            raise ReadOnlyStoreError("Cannot modify a read-only prompt store")

        prompt_uuid = str(uuid.uuid4())
        now = datetime.utcnow().isoformat()

        prompt_data = {
            "uuid": prompt_uuid,
            "content": content,
            "description": description,
            "version": 1,
            "versions": [
                {
                    "content": content,
                    "description": description,
                    "version": 1,
                    "created_at": now,
                }
            ],
            "tags": tags or [],
            "created_at": now,
            "updated_at": now,
        }

        index = self._load_index()
        index[prompt_uuid] = prompt_data
        self._save_index(index)

        return Prompt(
            uuid=prompt_uuid,
            content=content,
            description=description,
            version=1,
            tags=tags or [],
            timestamp=now,
        )

    def get(self, uuid: str, version: Optional[int] = None) -> Prompt:
        """Retrieve a prompt by its UUID."""
        index = self._load_index()
        if uuid not in index:
            raise PromptNotFoundError(f"Prompt with UUID {uuid} not found")

        prompt_data = index[uuid]

        if version:
            version_data = next(
                (v for v in prompt_data["versions"] if v["version"] == version), None
            )
            if not version_data:
                raise PromptNotFoundError(
                    f"Version {version} of prompt {uuid} not found"
                )
            content = version_data["content"]
            description = version_data["description"]
            timestamp = version_data["created_at"]
        else:
            content = prompt_data["content"]
            description = prompt_data["description"]
            timestamp = prompt_data["updated_at"]

        return Prompt(
            uuid=uuid,
            content=content,
            description=description,
            version=prompt_data["version"],
            tags=prompt_data["tags"],
            timestamp=timestamp,
        )

    def find(self, query: str, field: str = "description") -> List[Prompt]:
        """Search for prompts based on a query."""
        if field not in ("description", "content", "tags"):
            raise ValueError("Field must be 'description', 'content', or 'tags'")

        index = self._load_index()
        prompts = []

        for uuid, data in index.items():
            if field == "tags":
                if any(query.lower() in tag.lower() for tag in data["tags"]):
                    prompts.append(self._data_to_prompt(uuid, data))
            else:
                value = data.get(field, "")
                if value and query.lower() in value.lower():
                    prompts.append(self._data_to_prompt(uuid, data))

        return prompts

    def _data_to_prompt(self, uuid: str, data: Dict) -> Prompt:
        """Convert raw data to a Prompt object."""
        return Prompt(
            uuid=uuid,
            content=data["content"],
            description=data["description"],
            version=data["version"],
            tags=data["tags"],
            timestamp=data["updated_at"],
        )

    def merge(self, other: "PromptStore", override: bool = False):
        """Merge another PromptStore into this one."""
        if self.readonly:
            raise ReadOnlyStoreError("Cannot modify a read-only prompt store")

        our_index = self._load_index()
        their_index = other._load_index()

        for uuid, their_data in their_index.items():
            if uuid not in our_index or override:
                our_index[uuid] = their_data

        self._save_index(our_index)

    def __iter__(self) -> Iterator[Prompt]:
        """Iterate over all prompts in the store."""
        index = self._load_index()
        for uuid, data in index.items():
            yield self._data_to_prompt(uuid, data)

__init__(location, readonly=False)

Initialize a new PromptStore.

Parameters:

Name Type Description Default
location Union[str, Path]

Path to the directory where prompts will be stored

 required
readonly bool

If True, the store will be read-only

 False
Source code in src/promptstore/store.py 
12
13
14
15
16
17
18
19
20
21
22
def __init__(self, location: Union[str, Path], readonly: bool = False):
    """Initialize a new PromptStore.

    Args:
        location: Path to the directory where prompts will be stored
        readonly: If True, the store will be read-only
    """
    self.location = Path(location)
    self.readonly = readonly
    self.index_path = self.location / "index.json"
    self._init_storage()

__iter__()

Iterate over all prompts in the store.

Source code in src/promptstore/store.py 
216
217
218
219
220
def __iter__(self) -> Iterator[Prompt]:
    """Iterate over all prompts in the store."""
    index = self._load_index()
    for uuid, data in index.items():
        yield self._data_to_prompt(uuid, data)

_data_to_prompt(uuid, data)

Convert raw data to a Prompt object.

Source code in src/promptstore/store.py 
191
192
193
194
195
196
197
198
199
200
def _data_to_prompt(self, uuid: str, data: Dict) -> Prompt:
    """Convert raw data to a Prompt object."""
    return Prompt(
        uuid=uuid,
        content=data["content"],
        description=data["description"],
        version=data["version"],
        tags=data["tags"],
        timestamp=data["updated_at"],
    )

_init_storage()

Initialize the storage directory and index.

Source code in src/promptstore/store.py 
24
25
26
27
28
29
def _init_storage(self):
    """Initialize the storage directory and index."""
    self.location.mkdir(parents=True, exist_ok=True)

    if not self.index_path.exists() and not self.readonly:
        self._save_index({})

_load_index()

Load the prompt index.

Source code in src/promptstore/store.py 
31
32
33
34
35
36
def _load_index(self) -> Dict:
    """Load the prompt index."""
    if not self.index_path.exists():
        return {}
    with open(self.index_path, "r", encoding="utf-8") as f:
        return json.load(f)

_save_index(index)

Save the prompt index.

Source code in src/promptstore/store.py 
38
39
40
41
42
43
def _save_index(self, index: Dict):
    """Save the prompt index."""
    if self.readonly:
        raise ReadOnlyStoreError("Cannot modify a read-only prompt store")
    with open(self.index_path, "w", encoding="utf-8") as f:
        json.dump(index, f, indent=2, ensure_ascii=False)

add(content, description=None, tags=None)

Add a new prompt to the store.

Source code in src/promptstore/store.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
def add(
    self,
    content: str,
    description: Optional[str] = None,
    tags: Optional[List[str]] = None,
) -> Prompt:
    """Add a new prompt to the store."""
    if self.readonly:
        raise ReadOnlyStoreError("Cannot modify a read-only prompt store")

    prompt_uuid = str(uuid.uuid4())
    now = datetime.utcnow().isoformat()

    prompt_data = {
        "uuid": prompt_uuid,
        "content": content,
        "description": description,
        "version": 1,
        "versions": [
            {
                "content": content,
                "description": description,
                "version": 1,
                "created_at": now,
            }
        ],
        "tags": tags or [],
        "created_at": now,
        "updated_at": now,
    }

    index = self._load_index()
    index[prompt_uuid] = prompt_data
    self._save_index(index)

    return Prompt(
        uuid=prompt_uuid,
        content=content,
        description=description,
        version=1,
        tags=tags or [],
        timestamp=now,
    )

find(query, field='description')

Search for prompts based on a query.

Source code in src/promptstore/store.py 
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def find(self, query: str, field: str = "description") -> List[Prompt]:
    """Search for prompts based on a query."""
    if field not in ("description", "content", "tags"):
        raise ValueError("Field must be 'description', 'content', or 'tags'")

    index = self._load_index()
    prompts = []

    for uuid, data in index.items():
        if field == "tags":
            if any(query.lower() in tag.lower() for tag in data["tags"]):
                prompts.append(self._data_to_prompt(uuid, data))
        else:
            value = data.get(field, "")
            if value and query.lower() in value.lower():
                prompts.append(self._data_to_prompt(uuid, data))

    return prompts

from_dict(prompts, readonly=True) classmethod

Create a PromptStore from a dictionary.

Parameters:

Name Type Description Default
prompts Dict

Dictionary of prompt data

 required
readonly bool

If True, the store will be read-only

 True

Returns:

Name Type Description
PromptStore PromptStore

A prompt store initialized with the given prompts
Source code in src/promptstore/store.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
@classmethod
def from_dict(cls, prompts: Dict, readonly: bool = True) -> "PromptStore":
    """Create a PromptStore from a dictionary.

    Args:
        prompts: Dictionary of prompt data
        readonly: If True, the store will be read-only

    Returns:
        PromptStore: A prompt store initialized with the given prompts
    """
    import tempfile

    temp_dir = Path(tempfile.mkdtemp())
    store = cls(temp_dir, readonly=readonly)

    with open(store.index_path, "w", encoding="utf-8") as f:
        json.dump(prompts, f, indent=2, ensure_ascii=False)

    return store

from_file(path, readonly=True) classmethod

Create a PromptStore from a JSON file.

Parameters:

Name Type Description Default
path Union[str, Path]

Path to the JSON file containing prompts

 required
readonly bool

If True, the store will be read-only

 True

Returns:

Name Type Description
PromptStore PromptStore

A prompt store initialized with the prompts from the file
Source code in src/promptstore/store.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
@classmethod
def from_file(cls, path: Union[str, Path], readonly: bool = True) -> "PromptStore":
    """Create a PromptStore from a JSON file.

    Args:
        path: Path to the JSON file containing prompts
        readonly: If True, the store will be read-only

    Returns:
        PromptStore: A prompt store initialized with the prompts from the file
    """
    path = Path(path)
    if not path.exists():
        raise FileNotFoundError(f"Prompt file not found: {path}")

    if path.is_file():
        # If it's a single JSON file
        with open(path, "r", encoding="utf-8") as f:
            prompts = json.load(f)
    else:
        # If it's a directory containing an index.json
        index_path = path / "index.json"
        if not index_path.exists():
            raise FileNotFoundError(f"No index.json found in directory: {path}")
        with open(index_path, "r", encoding="utf-8") as f:
            prompts = json.load(f)

    return cls.from_dict(prompts, readonly=readonly)

get(uuid, version=None)

Retrieve a prompt by its UUID.

Source code in src/promptstore/store.py 
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def get(self, uuid: str, version: Optional[int] = None) -> Prompt:
    """Retrieve a prompt by its UUID."""
    index = self._load_index()
    if uuid not in index:
        raise PromptNotFoundError(f"Prompt with UUID {uuid} not found")

    prompt_data = index[uuid]

    if version:
        version_data = next(
            (v for v in prompt_data["versions"] if v["version"] == version), None
        )
        if not version_data:
            raise PromptNotFoundError(
                f"Version {version} of prompt {uuid} not found"
            )
        content = version_data["content"]
        description = version_data["description"]
        timestamp = version_data["created_at"]
    else:
        content = prompt_data["content"]
        description = prompt_data["description"]
        timestamp = prompt_data["updated_at"]

    return Prompt(
        uuid=uuid,
        content=content,
        description=description,
        version=prompt_data["version"],
        tags=prompt_data["tags"],
        timestamp=timestamp,
    )

merge(other, override=False)

Merge another PromptStore into this one.

Source code in src/promptstore/store.py 
202
203
204
205
206
207
208
209
210
211
212
213
214
def merge(self, other: "PromptStore", override: bool = False):
    """Merge another PromptStore into this one."""
    if self.readonly:
        raise ReadOnlyStoreError("Cannot modify a read-only prompt store")

    our_index = self._load_index()
    their_index = other._load_index()

    for uuid, their_data in their_index.items():
        if uuid not in our_index or override:
            our_index[uuid] = their_data

    self._save_index(our_index)

Prompt

promptstore.prompt.Prompt

Source code in src/promptstore/prompt.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
class Prompt:
    def __init__(
        self,
        uuid: str,
        content: str,
        version: int,
        description: Optional[str] = None,
        tags: Optional[List[str]] = None,
        timestamp: Optional[str] = None,
    ):
        self.uuid = uuid
        self.content = content
        self.description = description
        self.version = version
        self.tags = tags or []
        self.timestamp = timestamp
        self._template = Template(content)

    def fill(self, variables: dict) -> str:
        """Fill the prompt template with provided variables."""
        return self._template.render(**variables)

fill(variables)

Fill the prompt template with provided variables.

Source code in src/promptstore/prompt.py 
23
24
25
def fill(self, variables: dict) -> str:
    """Fill the prompt template with provided variables."""
    return self._template.render(**variables)

Exceptions

promptstore.exceptions

PromptNotFoundError

Bases: Exception

Raised when a prompt with the given UUID is not found.

Source code in src/promptstore/exceptions.py 
1
2
3
4
class PromptNotFoundError(Exception):
    """Raised when a prompt with the given UUID is not found."""

    pass

ReadOnlyStoreError

Bases: Exception

Raised when attempting to modify a read-only store.

Source code in src/promptstore/exceptions.py 
 7
 8
 9
10
class ReadOnlyStoreError(Exception):
    """Raised when attempting to modify a read-only store."""

    pass