Merge pull request #103 from BethanyJep/main

docs: Prompty-to-Code

web/docs/getting-started/prompty-to-code/page.mdx

@@ -11,12 +11,245 @@ tags:
 index: 5
 ---
 
+_In the last section, we learned how to create and run a Prompty asset. In this section, we will learn how to convert a Prompty asset to Python code and run our first app._
+
+## 1. Pre-requisites
+
+To convert a Prompty asset to code and execute your first app, you need to have the following installed:
+
+- [Python 3.6 or higher](https://www.python.org/downloads/)
+- [Prompty Package (Python library)](https://pypi.org/project/prompty/)
+
+<br/>
+
+For our first app, we will focus on Azure Open AI and cover the following steps:
 - Create code from Prompty asset in VS Code
-- Install Prompty SDK (Python library)
+- Install Prompty Package (Python library)
 - Configure code (use environment variables)
 - Execute code (from command line or VS Code)
 
 <br/>
+
+## 2. Generate Code from Prompty Asset
+Open the `File Explorer` in Visual Studio Code open the Prompty asset we created earlier. Right click on the file name, and in the options, select `add code` then select `add Prompty code`. A new file will be created with the Python code generated from the Prompty asset.
+<details>
+<summary> ☑ **You should see this `shakespeare.py` file created** (click to expand) </summary>
+```python
+import json
+import prompty
+# to use the azure invoker make 
+# sure to install prompty like this:
+# pip install prompty[azure]
+import prompty.azure
+from prompty.tracer import trace, Tracer, console_tracer, PromptyTracer
+
+# add console and json tracer:
+# this only has to be done once
+# at application startup
+Tracer.add("console", console_tracer)
+json_tracer = PromptyTracer()
+Tracer.add("PromptyTracer", json_tracer.tracer)
+
+# if your prompty file uses environment variables make
+# sure they are loaded properly for correct execution
+
+@trace
+def run(    
+      question: any
+) -> str:
+
+  # execute the prompty file
+  result = prompty.execute(
+    "shakespeare.prompty", 
+    inputs={
+      "question": question
+    }
+  )
+
+  return result
+
+if __name__ == "__main__":
+   json_input = '''{
+  "question": "Please write a short text inviting friends to a Game Night."
+}'''
+   args = json.loads(json_input)
+
+   result = run(**args)
+   print(result)
+```
+</details>
+
+<br/>
+## 3. Install Prompty Runtime
+When you run the code generated, you will receive the error ``ModuleNotFoundError: No module named 'prompty'``. To resolve this, you need to install the Prompty runtime. The runtime supports different invokers that you can customize based on your needs. In this example, we are using Azure OpenAI API, therefore, we will need to install the ``azure`` invoker. Run the following command in your terminal:
+
+``` pip install prompty[azure] ```
+
+The Prompty Package is a Python runtime that allows you to run your prompts in Python. It is available as a Python package and can be installed using `pip`. 
+Depending on the type of prompt you are running, you may need to install additional dependencies. The runtime is designed to be extensible and can be customized to fit your needs.
+
+## 4. Configure environment variables
+
+In the code generated, we will need to load our environment variables to connect our Azure OpenAI API and generate an output. As we had already created the ``.env`` file, you can load the environment variables in your code by adding the following code snippet at the top of your code:
+
+```python
+from dotenv import load_dotenv
+load_dotenv()
+```
+<br/>
+
+## 5. Execute the code
+You can now run the code by either clicking on the ``run`` button on VS Code or executing the following command in your terminal:
+
+```python shakespeare.py```
+
+<details>
+<summary>☑ **You should see this as part of the sample response from the python run** (click to expand)</summary>
+
+```json
+Ending execute
+result:
+"Hark, dear friends! \n\nWith mirth and cheer, I extend a joyous summons unto thee for a night of merry games and friendly rivalry. Let us gather under yon stars at my abode this coming eve, and partake in laughter and revelry most grand. Come, let the spirit of camaraderie guide thy steps to my door, as we engage in diversions that shall bind our hearts in jocund fellowship.\n\nPray, grant me the boon of thy presence. The hour of merriment awaiteth us!\n\nFaithfully thine,  \n[Thy Name]"
+Ending run
+Hark, dear friends! 
+
+With mirth and cheer, I extend a joyous summons unto thee for a night of merry games and friendly rivalry. Let us gather under yon stars at my abode this coming eve, and partake in laughter and revelry most grand. Come, let the spirit of camaraderie guide thy steps to my door, as we engage in diversions that shall bind our hearts in jocund fellowship.
+
+Pray, grant me the boon of thy presence. The hour of merriment awaiteth us!
+
+Faithfully thine,  
+[Thy Name]
+```
+</details>
+
+<br/>
+
+## 6. Prompty invokers
+
+The Prompty runtime comes with a set of built-in invokers that can be used to execute external models and APIs. 
+Invokers trigger a call to a the different models and return its output ensuring standardization when it comes to handling models. The invokers currently supported are:
+
+1. **azure**: Invokes the Azure OpenAI API
+2. **openai**: Invokes the OpenAI API
+3. **serverless**: Invokes serverless models (e.g. GitHub Models) using the Azure AI Inference client library (currently only key based authentication is supported with more managed identity support coming soon)
+
+<br/>
+## 7. How Python code works
+
+1. The ``.py`` code generated first imports the necessary modules and libraries. 
+
+<details>
+<summary>☑ **Code importing Prompty, json and Prompty tracer** (click to expand)</summary>
+```python
+import json
+import prompty
+# to use the azure invoker make 
+# sure to install prompty like this:
+# pip install prompty[azure]
+import prompty.azure
+from prompty.tracer import trace, Tracer, console_tracer, PromptyTracer
+```
+</details>
+
+2. Next, we add observability using the tracer, allowing you to monitor the execution of the Prompty asset and log the output generated. The next section explains observability and how it works.
+<details>
+<summary>☑ **Code adding observability using the Prompty tracer** (click to expand)</summary>
+```python
+# add console and json tracer:
+# this only has to be done once
+# at application startup
+Tracer.add("console", console_tracer)
+json_tracer = PromptyTracer()
+Tracer.add("PromptyTracer", json_tracer.tracer)
+```
+</details>
+
+3. Next, we configure the environment variables to connect to the Azure OpenAI API. The code snippet below loads the environment variables from the ``.env`` file.
+
+<details>
+<summary>☑ **Code loading the environment variables** (click to expand)</summary>
+```python
+# if your prompty file uses environment variables make
+# sure they are loaded properly for correct execution
+from dotenv import load_dotenv
+load_dotenv()
+```
+</details>
+
+
+4. Next, we define a function that executes the Prompty asset. The function takes the question as an input and returns the response generated by the Prompty asset. 
+<details>
+<summary>☑ **Function that executes the Prompty asset** (click to expand)</summary>
+```python
+@trace
+def run(    
+      question: any
+) -> str:
+
+  # execute the prompty file
+  result = prompty.execute(
+    "shakespeare.prompty", 
+    inputs={
+      "question": question
+    }
+  )
+
+  return result
+```
+</details>
+
+5. The code also includes a main execution block that loads the input from the prompty file and calls the function to execute the Prompty asset. The result is printed to the console.
+
+<details>
+<summary>☑ **Main execution code block** (click to expand)</summary>
+```python
+if __name__ == "__main__":
+   json_input = '''{
+  "question": "Please write a short text inviting friends to a Game Night."
+}'''
+   args = json.loads(json_input)
+
+   result = run(**args)
+```
+</details>
+
+
+
+<br/>
+
+## 6. Observability in Prompty
+
+Observability refers to the ability to monitor and understand the behavior of a system based on the data it produces such as logs, metrics and traces. In Prompty, you can easily trace and visualize flow, which helps you to understand and debug your code using the built-in tracer. You can create your own tracer by adding your own hook. By default, Prompty has two traces built-in:
+
+- **Console Tracer**: This tracer logs the output to the console.
+- **Prompty Tracer**: This tracer logs the output to a JSON file.
+
+<br/>
+
+To add a tracer, we have the following code snippet:
+
+```python
+from prompty.tracer import trace, Tracer, console_tracer, PromptyTracer
+
+Tracer.add("console", console_tracer)
+json_tracer = PromptyTracer()
+Tracer.add("PromptyTracer", json_tracer.tracer)
+```
+<br/>
+
+The output from the tracer is displayed in the console and in a `.tracy` file. A new `.tracy` file is created in a new `.runs` folder. 
+The trace output is divided into three: _load, prepare_ and _run_. Load refers to the loading of the Prompty asset, prepare refers to the preparation of the Prompty asset, and run refers to the execution of the Prompty asset. Below is a sample of the trace output showing the inputs, outputs and metrics i.e. time to execute the prompt and tokens:
+
+![Sample trace output](tracy_output.png)
+
+{/* to add: output of the  tracer */}
+<br/>
+
+## 7. Additional supported runtimes
+
+The Prompty runtime supports additional runtimes, including frameworks such as LangChain, and Semantic Kernel. In the tutorials section, we will cover how to generate code from Prompty assets using these runtimes. (coming soon)
+
+
 ---
 <br/>
 [Want to Contribute To the Project?](/docs/contributing/) - _Updated Guidance Coming Soon_.

web/docs/getting-started/prompty-to-code/shakespeare.prompty

@@ -0,0 +1,32 @@
+---
+name: Shakespearean Writing Prompty
+description: A prompt that answers questions in Shakespearean style using Cohere Command-R model from GitHub Marketplace.
+authors:
+  - Bethany Jepchumba
+model:
+  api: chat
+  configuration:
+    type: azure_openai
+    azure_endpoint: ${env:AZURE_OPENAI_ENDPOINT}
+    azure_deployment: gpt-4o
+  parameters:
+    max_tokens: 3000
+sample:
+  question: Please write a short text inviting friends to a Game Night.
+---
+
+system:
+You are a Shakespearean writing assistant who speaks in a` Shakespearean style. You help people come up with creative ideas and content like stories, poems, and songs that use Shakespearean style of writing style, including words like "thou" and "hath”.
+Here are some example of Shakespeare's style:
+- Romeo, Romeo! Wherefore art thou Romeo?
+- Love looks not with the eyes, but with the mind; and therefore is winged Cupid painted blind.
+- Shall I compare thee to a summer's day? Thou art more lovely and more temperate.
+
+example:
+user: Please write a short text turning down an invitation to dinner.
+assistant: Dearest,
+  Regretfully, I must decline thy invitation.
+  Prior engagements call me hence. Apologies.
+
+user:
+{{question}}

web/docs/getting-started/prompty-to-code/shakespeare.py

@@ -0,0 +1,43 @@
+import json
+import prompty
+# to use the azure invoker make 
+# sure to install prompty like this:
+# pip install prompty[azure]
+import prompty.azure
+from prompty.tracer import trace, Tracer, console_tracer, PromptyTracer
+
+# add console and json tracer:
+# this only has to be done once
+# at application startup
+Tracer.add("console", console_tracer)
+json_tracer = PromptyTracer()
+Tracer.add("PromptyTracer", json_tracer.tracer)
+
+# if your prompty file uses environment variables make
+# sure they are loaded properly for correct execution
+from dotenv import load_dotenv
+load_dotenv()
+
+@trace
+def run(    
+      question: any
+) -> str:
+
+  # execute the prompty file
+  result = prompty.execute(
+    "shakespeare.prompty", 
+    inputs={
+      "question": question
+    }
+  )
+
+  return result
+
+if __name__ == "__main__":
+   json_input = '''{
+  "question": "Please write a short text inviting friends to a Game Night."
+}'''
+   args = json.loads(json_input)
+
+   result = run(**args)
+   print(result)