# Prompt Matrix
[](https://badge.fury.io/py/prompt-matrix)
[](https://badge.fury.io/py/prompt-matrix)
[](https://opensource.org/licenses/MIT)
A Python package to expand prompt matrix strings. For example, the string `"The
<dog|cat> in the hat"` expands to the list `["The dog in the hat", "The cat in
the hat"]`.
The motivating case for this package is to compare the effects of different
prompts in text and image generation systems such as Stable Diffusion and GPT-3.
## Features
A prompt string may contain multiple alternations. For example, `"The <dog|cat>
in the <cardigan|hat>"` produces a list of the four strings `"The dog in the
cardigan"`, `"The dog in the hat"`, `"The cat in the cardigan"`, and `"The cat
in the hat"`.
A prompt string may contain nested alternations. For example, `"The
<<small|large> dog|cat>"` produces the strings `"The small dog"`, `"The large
do"`, and `"The cat"`.
Brackets `[]` enclose optional elements. For example, `"The [small] cat"` is
equivalent to `"The <small,> cat"`, and both produce the strings `"The small
cat"` and `"The cat"`.
The special characters `<>{}|` can be replaced by different strings, or disabled
by specifying
`None` or the empty string.
> **Note**: The disjunction is bounded by the enclosing brackets, if any. `"The
dog|cat in the cardigan|hat"` generates the three strings `"The dog"`, `"cat in
the gardigan"`, and `"hat"`. This is in contrast to some other systems, that
scope a disjunction to the text delimited by surrounding whitespace.
## Install
```shell
$ pip install prompt-matrix
```
## Usage
Prompt Matrix provides two functions for expanding a prompt matrix:
`expand` and `iterexpand`. Both take a string that specifies
a prompt matrix.
**`expand`** returns an array of strings with all possible combinations of the
prompt matrix elements.
```python
import prompt_matrix
prompt = "<hi|hello> <there|you>"
expansion = prompt_matrix.expand(prompt)
print(expansion) # ["hi there", "hi you", "hello there", "hello you"]
```
**`iterexpand`** returns a generator that yields the expansions one by
one.
```python
import prompt_matrix
prompt = "<hi|hello> <there|you>"
for expansion in prompt_matrix.iterexpand(prompt):
print(expansion) # "hi there", "hi you", "hello there", "hello you"
```
### Examples
Example 1: Basic usage
```python
import prompt_matrix
prompt_matrix.expand("The <dog|cat> in the hat")
# ->
# ["The dog in the hat",
# "The cat in the hat"]
```
Example 2: Using multiple alternations
```python
prompt_matrix.expand("The <dog|cat> in the <cardigan|hat>")
# ->
# ["The dog in the cardigan",
# "The dog in the hat",
# "The cat in the cardigan",
# "The cat in the hat"]
```
Example 3: Using nested brackets
```python
prompt_matrix.expand("The <<small|large> <brown|black> dog|<red|blue> fish>")
# ->
# ["The small brown dog",
# "The small black dog",
# "The large brown dog",
# "The large black dog",
# "The red fish",
# "The blue fish"]
```
Example 4: Using custom brackets and separator
```python
prompt_matrix.expand("The {dog,cat} in the {cardigan,hat}",
brackets=['{', '}'], alt=',')
# ->
# ["The dog in the cardigan",
# "The dog in the hat",
# "The cat in the cardigan",
# "The cat in the hat"]
```
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://osteele.github.io/prompt-matrix.py/",
"name": "prompt-matrix",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "prompt-engineering",
"author": "Oliver Steele",
"author_email": "steele@osteele.com",
"download_url": "https://files.pythonhosted.org/packages/40/c3/c2131ef06b660b61d053ffedf53ec71c87afbe34e3580a031fc1a07f8280/prompt_matrix-0.1.4.tar.gz",
"platform": null,
"description": "# Prompt Matrix\n\n[](https://badge.fury.io/py/prompt-matrix)\n[](https://badge.fury.io/py/prompt-matrix)\n[](https://opensource.org/licenses/MIT)\n\nA Python package to expand prompt matrix strings. For example, the string `\"The\n<dog|cat> in the hat\"` expands to the list `[\"The dog in the hat\", \"The cat in\nthe hat\"]`.\n\nThe motivating case for this package is to compare the effects of different\nprompts in text and image generation systems such as Stable Diffusion and GPT-3.\n\n## Features\n\nA prompt string may contain multiple alternations. For example, `\"The <dog|cat>\nin the <cardigan|hat>\"` produces a list of the four strings `\"The dog in the\ncardigan\"`, `\"The dog in the hat\"`, `\"The cat in the cardigan\"`, and `\"The cat\nin the hat\"`.\n\nA prompt string may contain nested alternations. For example, `\"The\n<<small|large> dog|cat>\"` produces the strings `\"The small dog\"`, `\"The large\ndo\"`, and `\"The cat\"`.\n\nBrackets `[]` enclose optional elements. For example, `\"The [small] cat\"` is\nequivalent to `\"The <small,> cat\"`, and both produce the strings `\"The small\ncat\"` and `\"The cat\"`.\n\nThe special characters `<>{}|` can be replaced by different strings, or disabled\nby specifying\n`None` or the empty string.\n\n> **Note**: The disjunction is bounded by the enclosing brackets, if any. `\"The\ndog|cat in the cardigan|hat\"` generates the three strings `\"The dog\"`, `\"cat in\nthe gardigan\"`, and `\"hat\"`. This is in contrast to some other systems, that\nscope a disjunction to the text delimited by surrounding whitespace.\n\n## Install\n\n```shell\n$ pip install prompt-matrix\n```\n\n## Usage\n\nPrompt Matrix provides two functions for expanding a prompt matrix:\n`expand` and `iterexpand`. Both take a string that specifies\na prompt matrix.\n\n**`expand`** returns an array of strings with all possible combinations of the\nprompt matrix elements.\n\n```python\nimport prompt_matrix\n\nprompt = \"<hi|hello> <there|you>\"\nexpansion = prompt_matrix.expand(prompt)\nprint(expansion) # [\"hi there\", \"hi you\", \"hello there\", \"hello you\"]\n```\n\n**`iterexpand`** returns a generator that yields the expansions one by\none.\n\n```python\nimport prompt_matrix\n\nprompt = \"<hi|hello> <there|you>\"\nfor expansion in prompt_matrix.iterexpand(prompt):\n print(expansion) # \"hi there\", \"hi you\", \"hello there\", \"hello you\"\n```\n\n### Examples\n\nExample 1: Basic usage\n\n```python\nimport prompt_matrix\n\nprompt_matrix.expand(\"The <dog|cat> in the hat\")\n# ->\n# [\"The dog in the hat\",\n# \"The cat in the hat\"]\n```\n\nExample 2: Using multiple alternations\n\n```python\nprompt_matrix.expand(\"The <dog|cat> in the <cardigan|hat>\")\n# ->\n# [\"The dog in the cardigan\",\n# \"The dog in the hat\",\n# \"The cat in the cardigan\",\n# \"The cat in the hat\"]\n```\n\nExample 3: Using nested brackets\n\n```python\nprompt_matrix.expand(\"The <<small|large> <brown|black> dog|<red|blue> fish>\")\n# ->\n# [\"The small brown dog\",\n# \"The small black dog\",\n# \"The large brown dog\",\n# \"The large black dog\",\n# \"The red fish\",\n# \"The blue fish\"]\n```\n\nExample 4: Using custom brackets and separator\n\n```python\nprompt_matrix.expand(\"The {dog,cat} in the {cardigan,hat}\",\n brackets=['{', '}'], alt=',')\n# ->\n# [\"The dog in the cardigan\",\n# \"The dog in the hat\",\n# \"The cat in the cardigan\",\n# \"The cat in the hat\"]\n```\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Expand a prompt matrix strings into a list of prompts.",
"version": "0.1.4",
"split_keywords": [
"prompt-engineering"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6fc06d8b5b1ca423d4e92a3f9075902f719c41d72a7f188a52cb3d828fd8611b",
"md5": "308db3e3ad967ec4357a1ca684908c5d",
"sha256": "53fc5822897f820c9d6776f3f4994364d00daffd4b2cfc9dfab6df8306b2e16d"
},
"downloads": -1,
"filename": "prompt_matrix-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "308db3e3ad967ec4357a1ca684908c5d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 5926,
"upload_time": "2023-03-20T08:43:40",
"upload_time_iso_8601": "2023-03-20T08:43:40.253166Z",
"url": "https://files.pythonhosted.org/packages/6f/c0/6d8b5b1ca423d4e92a3f9075902f719c41d72a7f188a52cb3d828fd8611b/prompt_matrix-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "40c3c2131ef06b660b61d053ffedf53ec71c87afbe34e3580a031fc1a07f8280",
"md5": "ebe7a18205f675007e48e0282001bd23",
"sha256": "07350cb54aaca60e2fb8106e463053cd97c606064cb31e0a865a4a8b7e8d22e9"
},
"downloads": -1,
"filename": "prompt_matrix-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "ebe7a18205f675007e48e0282001bd23",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 4719,
"upload_time": "2023-03-20T08:43:41",
"upload_time_iso_8601": "2023-03-20T08:43:41.336648Z",
"url": "https://files.pythonhosted.org/packages/40/c3/c2131ef06b660b61d053ffedf53ec71c87afbe34e3580a031fc1a07f8280/prompt_matrix-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-20 08:43:41",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "prompt-matrix"
}
JSON