Merge pull request #8 from narenaryan/feat/add-props

[Draft] feat: Add support for variables and metadata custom properties

.github/workflows/pylint.yml

@@ -7,16 +7,16 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.x'
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install pylint
-        pip install -r requirements.txt
-    - name: Analysing the code with pylint
-      run: |
-        pylint $(git ls-files 'src/*.py')
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pylint
+          pip install -r requirements.txt
+      - name: Analysing the code with pylint
+        run: |
+          pylint $(git ls-files 'src/*.py') --fail-under=9

README.md

@@ -1,33 +1,42 @@
 # PromptML (Prompt Markup Language)
-A simple, yet elegant markup language for defining AI Prompts as Code (APaC). Built to be used by AI agents to automatically prompt for other AI systems
+
+![](./promptml.jpeg)
+
+<i>A simple, yet elegant markup language for defining AI Prompts as Code (APaC). Built to be used by AI agents to automatically prompt for other AI systems.</i>
 
 The architecture is shown as below. A `PromptML` prompt can be version controlled like any other code file. Using promptml parser package, one can easily generate a natural language prompt, and execute it against a LLM. See examples for using promptml library package: [open examples](./examples/)
 
 ![prompt-ml architecture](./prompt-github.png)
 
 ## Why PromptML ?
+
 PromptML is built to provide a way for prompt engineers to define the AI prompts in a deterministic way. This is a Domain Specific Language (DSL) which defines characteristics of a prompt including context, objective, instructions and it's metadata.
 A regular prompt is an amalgamation of all these aspects into one entity. PromptML splits it into multiple sections and makes the information explicit.
 
 The language grammar can be found here: [grammar.lark](./src/promptml/grammar.lark)
 
-
 ## How PromptML looks ?
+
 The language is simple. You start blocks with `@` section annotation. A section ends with `@end` marker. Comments are started with `#` key. The prompt files ends with `.pml` extension.
 
 ```pml
 @prompt
+    # Add task context
     @context
-    # Add prompt context
     @end
+
+    # Add task objective
     @objective
     # This is the final question or ask
     @end
+
+    # Add one or more instructions to execute the prompt
     @instructions
         @step
-        # Add one or more instructions to execute the prompt
         @end
     @end
+
+    # Add one or more examples
     @examples
         @example
             @input
@@ -38,31 +47,40 @@ The language is simple. You start blocks with `@` section annotation. A section
             @end
         @end
     @end
+
+    # Add task constraints
     @constraints
-    # Add prompt constraints
+        @length min: 1 max: 10  @end
     @end
+
+    # Add prompt category
+    @category
+    @end
+
+    # Add custom metadata
     @metadata
-    # Add prompt metadata here
     @end
 @end
 ```
 
-See [prompt.pml](./prompt.pml) to see an example.
+See [prompt.pml](./prompt.pml) to see for complete syntax.
 
 ## Design
+
 Regular text prompts are very abstract in nature. Natural languages are very flexible but provides least reliability. How to provide context for an AI system and ask something ? Shouldn't we specify that explicitly.
 PromptML is an attempt to make contents of a prompt explicit with a simple language.
 
 ## Core tenets of PromptML
+
 Below are the qualities PromptML brings to prompt engineering domain:
 
 1. Standardization instead of fragmentation
 2. Collaboration instead of confusion
 3. Enabling version control-ability
 4. Promoting verbosity for better results
 
-
 ## Why not use XML, YAML, or JSON for PromptML ?
+
 First, XML, JSON, and YAML are not DSL languages. They are data formats that can represent any form of data. Second, generative AI needs a strict, yet flexible data language with fixed constraints which evolve along with the domain.
 
 PromptML is built exactly to solve those two issues.
@@ -72,10 +90,13 @@ Language grammar is influenced by XML & Ruby, so if you know any one of them, yo
 ## Usage
 
 1. Install Python requirements
+
 ```bash
 pip install -r requirements.txt
 ```
+
 2. import the parser and parse a promptML file
+
 ```py
 from promptml.parser import PromptParser
 
@@ -106,17 +127,18 @@ promptml_code = '''
             @end
         @end
 
+        @category
+            Prompt Management
+        @end
+
         @constraints
-            @length min: 1 max: 10
+            @length min: 1 max: 10 @end
         @end
 
         @metadata
-            @domain
-                Web Development
-            @end
-            @difficulty
-                Advaned
-            @end
+            top_p: 0.9
+            n: 1
+            team: promptml
         @end
     @end
 '''
@@ -128,17 +150,38 @@ print(prompt)
 # Output: {
 #     'context': 'This is the context section.',
 #     'objective': 'This is the objective section.',
+#     'category': 'Prompt Management',
 #     'instructions': ['Step 1'],
 #     'examples': [
 #         {'input': 'Input example 1', 'output': 'Output example 1'}
 #     ],
 #     'constraints': {'length': {'min': 1, 'max': 10}},
-#     'metadata': {'domain': 'Web Development', 'difficulty': 'Advanced'}
+#     'metadata': {'top_p': 0.9, 'n': 1, 'team': 'promptml'}
 # }
+```
+
+## Defining variables
+
+You can define variables in the promptML file and use them in the prompt `context` and `objective`. The variables are defined in the `@vars` section and referenced using `$var` syntax in either `context` or `objective` sections.
+
+```pml
+@vars
+    name = "John Doe"
+@end
+
+@prompt
+    @context
+        You are a name changing expert.
+    @end
 
+    @objective
+        You have to change the name: $name to an ancient name.
+    @end
+@end
 ```
 
 ## TODO
+
 We are currently working on:
 
 1. Supporting more annotations (Ex: temperature, top_p)

prompt.pml

@@ -1,72 +1,87 @@
-# Prompt Description for a task
+# Define prompt variables
+@vars
+    role = 'highly skilled and experienced software developer'
+@end
+
+# Define prompt
 @prompt
   # Context is used to provide background information or context for the task
   @context
-    You are a highly skilled and experienced software developer with expertise in various programming languages and frameworks. You have been tasked with creating a new web application for a social media platform.
+      You are a $role with expertise in various programming languages and frameworks. You have been tasked with creating a new web application for a social media platform.
   @end
 
   # Objective is used to define the main goal or objective of the task
   @objective
-    Design and implement the core architecture and components for a scalable and efficient web application that can handle a large number of concurrent users while providing a seamless and responsive user experience.
+      Design and implement the core architecture and components for a scalable and efficient web application that can handle a large number of concurrent users while providing a seamless and responsive user experience.
   @end
 
   # Instructions are used to provide detailed steps or guidelines for completing the task
   @instructions
-    # steps can be used to break down the task into smaller parts
-    @step
-      Identify the key features and requirements of the web application based on the provided context.
-    @end
-    @step
-      Propose a suitable architecture (e.g., monolithic, microservices, etc.) and justify your choice.
-    @end
-    @step
-      Outline the essential components or modules of the application, such as user authentication, data storage, real-time communication, and so on.
-    @end
-    @step
-      Discuss the potential technologies, frameworks, and tools you would use to implement each component, highlighting their strengths and trade-offs.
-    @end
-    @step
-      Address scalability and performance concerns, including techniques for load balancing, caching, and database optimization.
-    @end
-    @step
-      Describe how you would ensure the security and privacy of user data, including authentication, authorization, and data encryption.
-    @end
+      # steps can be used to break down the task into smaller parts
+      @step
+          Identify the key features and requirements of the web application based on the provided context.
+      @end
+      @step
+          Propose a suitable architecture (e.g., monolithic, microservices, etc.) and justify your choice.
+      @end
+      @step
+          Outline the essential components or modules of the application, such as user authentication, data storage, real-time communication, and so on.
+      @end
+      @step
+          Discuss the potential technologies, frameworks, and tools you would use to implement each component, highlighting their strengths and trade-offs.
+      @end
+      @step
+          Address scalability and performance concerns, including techniques for load balancing, caching, and database optimization.
+      @end
+      @step
+          Describe how you would ensure the security and privacy of user data, including authentication, authorization, and data encryption.
+      @end
   @end
 
   # Examples are used to provide sample inputs and outputs for the task
   @examples
-    @example
-      @input 
-        Design the core architecture and components for a large-scale e-commerce web application.
+      @example
+          @input
+              Design the core architecture and components for a large-scale e-commerce web application.
+          @end
+          @output
+              For a large-scale e-commerce web application, a microservices architecture would be suitable due to its inherent scalability and flexibility...
+          @end
       @end
-      @output
-        For a large-scale e-commerce web application, a microservices architecture would be suitable due to its inherent scalability and flexibility...
+      @example
+          @input
+              Outline main components for a large-scale e-commerce web application.
+          @end
+          @output
+              Product Catalog, User Management, Order Processing, Payment Gateway, Search Engine, Recommendation Engine are the main components of a large-scale e-commerce web application...
+          @end
       @end
-    @end
-    @example
-      @input  
-        Outline main components for a large-scale e-commerce web application.
-      @end
-      @output 
-        Product Catalog, User Management, Order Processing, Payment Gateway, Search Engine, Recommendation Engine are the main components of a large-scale e-commerce web application...
-      @end
-    @end
   @end
 
   # Constraints are used to specify any limitations or restrictions for the task
   @constraints
-    @length
-      min: 1000
-      max: 3000
-    @end
-    @tone
-        Professional and technical 
-    @end
+      @length
+          min: 1000
+          max: 3000
+      @end
+      @tone
+          Professional and technical
+      @end
+      @difficulty
+          Advanced
+      @end
+  @end
+
+  # categories are used to classify the task into different categories
+  @category
+      Software Engineering
   @end
 
-  # Metadata includes information such as domain, difficulty, skills, and tags
+  # Metadata includes information such as domain, difficulty, custom props, etc.
   @metadata
-    @domain Software Engineering, Web Development @end
-    @difficulty Advanced @end
+      top_p: 0.6
+      temperature: 0.5
+      n: 1
+      internal: 'true'
   @end
 @end