UPDATE

Author: mazzasaverio

config/README.md

@@ -0,0 +1,92 @@
+# Custom YAML Schema Configuration
+
+This directory contains YAML schema files for custom data extraction. Each YAML file defines both the extraction schema and the system prompt in a single, organized format.
+
+## Schema Structure
+
+Each YAML schema file must contain the following required fields:
+
+```yaml
+# Schema metadata
+name: "Schema Name"
+description: "Brief description of what this schema extracts"
+
+# System prompt for the LLM
+system_prompt: |
+  Detailed instructions for the LLM on how to extract data.
+  This can be multiple lines and should provide clear guidance
+  on what information to look for and how to handle edge cases.
+
+# JSON Schema definition
+schema:
+  type: object
+  properties:
+    field_name:
+      type: string
+      description: "Description of this field"
+    # Add more properties as needed
+  required: ["field_name"]
+  additionalProperties: false
+```
+
+## Available Commands
+
+### List Available Custom Schemas
+```bash
+structured-output list-schemas
+```
+
+### Extract Using Custom YAML Schema
+```bash
+structured-output extract-custom SCHEMA_NAME --text "Your text here"
+```
+
+Or from a file:
+```bash
+structured-output extract-custom SCHEMA_NAME --input-file input.txt
+```
+
+### Save Results
+```bash
+structured-output extract-custom SCHEMA_NAME --input-file input.txt --output results.json
+```
+
+### List Predefined Templates
+```bash
+structured-output list-templates
+```
+
+### Extract Using Predefined Template
+```bash
+structured-output extract job --text "Your job description here"
+structured-output extract recipe --text "Your recipe text here"
+```
+
+## Example Usage
+
+1. Create a new YAML schema file in this directory (e.g., `my_schema.yaml`)
+2. Define your schema structure following the format above
+3. List available schemas: `structured-output list-schemas`
+4. Use your schema: `structured-output extract-custom my_schema --text "Sample text"`
+
+## Pre-built Custom Schemas
+
+The following example schemas are included:
+
+- `news_article.yaml` - Extract structured information from news articles
+- `product_review.yaml` - Extract structured information from product reviews  
+- `customer_support.yaml` - Extract structured information from support tickets
+
+## Schema Validation
+
+The system automatically validates:
+- Required fields (name, description, system_prompt, schema)
+- JSON schema structure (must be type: object with properties)
+- YAML syntax correctness
+
+## Configuration Options
+
+- `--config-dir`: Specify a different directory for YAML schemas (default: `config/schemas`)
+- `--pretty`: Pretty print JSON output
+- `--no-save`: Don't save results to file, only print to stdout
+- `--output`: Specify custom output file path 

config/schemas/customer_support.yaml

@@ -0,0 +1,62 @@
+# Customer Support Ticket Extraction Schema
+name: "Customer Support Ticket"
+description: "Extract structured information from customer support tickets or emails"
+
+# System prompt for extraction
+system_prompt: |
+  Extract structured information from the following customer support ticket or email.
+  Focus on identifying:
+  - Customer information and contact details
+  - Issue category and priority level
+  - Product or service affected
+  - Detailed problem description
+  - Resolution status and actions taken
+  
+  If information is not explicitly mentioned, leave fields as null or empty.
+
+# JSON Schema definition
+schema:
+  type: object
+  properties:
+    ticket_id:
+      type: ["string", "null"]
+      description: "Support ticket ID if mentioned"
+    customer_name:
+      type: ["string", "null"]
+      description: "Customer's name"
+    customer_email:
+      type: ["string", "null"]
+      description: "Customer's email address"
+    issue_category:
+      type: ["string", "null"]
+      description: "Category of the issue (billing, technical, account, etc.)"
+    priority_level:
+      type: ["string", "null"]
+      description: "Priority level (low, medium, high, urgent)"
+    product_service:
+      type: ["string", "null"]
+      description: "Product or service the issue relates to"
+    issue_summary:
+      type: string
+      description: "Brief summary of the issue"
+    detailed_description:
+      type: string
+      description: "Detailed description of the problem"
+    steps_to_reproduce:
+      type: array
+      items:
+        type: string
+      description: "Steps to reproduce the issue if mentioned"
+    resolution_status:
+      type: ["string", "null"]
+      description: "Current status (open, in-progress, resolved, closed)"
+    actions_taken:
+      type: array
+      items:
+        type: string
+      description: "Actions taken to resolve the issue"
+    escalation_needed:
+      type: ["boolean", "null"]
+      description: "Whether the issue needs escalation"
+  required: ["ticket_id", "customer_name", "customer_email", "issue_category", "priority_level", "product_service", "issue_summary", "detailed_description", "steps_to_reproduce", "resolution_status", "actions_taken", "escalation_needed"]
+  additionalProperties: false 

config/schemas/news_article.yaml

@@ -0,0 +1,53 @@
+# News Article Extraction Schema
+name: "News Article"
+description: "Extract structured information from news articles"
+
+# System prompt for extraction
+system_prompt: |
+  Extract structured information from the following news article.
+  Focus on identifying:
+  - Main headline and brief summary
+  - Publication details (date and author if mentioned)
+  - Geographic location mentioned in the news
+  - Key people and organizations mentioned
+  - News category and sentiment
+  
+  If information is not explicitly mentioned, leave the field as null.
+
+# JSON Schema definition
+schema:
+  type: object
+  properties:
+    headline:
+      type: string
+      description: "Main headline of the news article"
+    summary:
+      type: string
+      description: "Brief summary of the article"
+    publication_date:
+      type: ["string", "null"]
+      description: "Publication date if mentioned"
+    author:
+      type: ["string", "null"]
+      description: "Author name if mentioned"
+    location:
+      type: ["string", "null"]
+      description: "Geographic location mentioned in the news"
+    key_people:
+      type: array
+      items:
+        type: string
+      description: "Names of key people mentioned in the article"
+    organizations:
+      type: array
+      items:
+        type: string
+      description: "Organizations or companies mentioned"
+    category:
+      type: ["string", "null"]
+      description: "News category (politics, technology, sports, etc.)"
+    sentiment:
+      type: ["string", "null"]
+      description: "Overall sentiment of the article (positive, negative, neutral)"
+  required: ["headline", "summary", "publication_date", "author", "location", "key_people", "organizations", "category", "sentiment"]
+  additionalProperties: false 

config/schemas/product_review.yaml

@@ -0,0 +1,59 @@
+# Product Review Extraction Schema
+name: "Product Review"
+description: "Extract structured information from product reviews"
+
+# System prompt for extraction
+system_prompt: |
+  Extract structured information from the following product review.
+  Focus on identifying:
+  - Product name and brand
+  - Reviewer information and rating
+  - Key features mentioned (pros and cons)
+  - Purchase details if mentioned
+  - Overall sentiment and recommendation
+  
+  If information is not available, leave fields as null or empty arrays.
+
+# JSON Schema definition
+schema:
+  type: object
+  properties:
+    product_name:
+      type: string
+      description: "Name of the product being reviewed"
+    brand:
+      type: ["string", "null"]
+      description: "Brand or manufacturer name"
+    rating:
+      type: ["number", "null"]
+      description: "Numerical rating (e.g., out of 5 stars)"
+    reviewer_name:
+      type: ["string", "null"]
+      description: "Name of the reviewer if mentioned"
+    review_date:
+      type: ["string", "null"]
+      description: "Date of the review if mentioned"
+    verified_purchase:
+      type: ["boolean", "null"]
+      description: "Whether this is a verified purchase"
+    pros:
+      type: array
+      items:
+        type: string
+      description: "Positive aspects mentioned in the review"
+    cons:
+      type: array
+      items:
+        type: string
+      description: "Negative aspects mentioned in the review"
+    overall_sentiment:
+      type: ["string", "null"]
+      description: "Overall sentiment (positive, negative, neutral, mixed)"
+    would_recommend:
+      type: ["boolean", "null"]
+      description: "Whether the reviewer would recommend the product"
+    price_mentioned:
+      type: ["string", "null"]
+      description: "Price mentioned in the review if any"
+  required: ["product_name", "brand", "rating", "reviewer_name", "review_date", "verified_purchase", "pros", "cons", "overall_sentiment", "would_recommend", "price_mentioned"]
+  additionalProperties: false 

examples/README.md

@@ -0,0 +1,56 @@
+# Examples
+
+This directory contains example files demonstrating the usage of the Structured Output Cookbook.
+
+## Files
+
+### `example_usage.py`
+A comprehensive Python script showing how to use the library programmatically with:
+- Predefined templates (job descriptions, recipes)
+- Custom YAML schemas
+- Schema validation
+
+### `job_description.txt`
+Sample job description for testing job extraction template.
+
+### `news_article.txt`
+Sample news article for testing custom news extraction schema.
+
+### `recipe.txt`
+Sample recipe for testing recipe extraction template.
+
+## Running Examples
+
+### CLI Usage
+```bash
+# List available predefined templates
+structured-output list-templates
+
+# List available custom schemas
+structured-output list-schemas
+
+# Extract using predefined template
+structured-output extract recipe --input-file examples/recipe.txt --pretty
+
+# Extract using custom YAML schema
+structured-output extract-custom news_article --input-file examples/news_article.txt --pretty
+```
+
+### Programmatic Usage
+```bash
+# Run the comprehensive example
+python examples/example_usage.py
+```
+
+## Creating Custom Schemas
+
+1. Create a new YAML file in `config/schemas/`
+2. Follow the structure defined in `config/README.md`
+3. Test your schema with the CLI or programmatically
+
+## Environment Setup
+
+Make sure you have your OpenAI API key set:
+```bash
+export OPENAI_API_KEY="your-api-key-here"
+```