Add comprehensive JSON prompt use cases and integrations

This update significantly enhances the JSON-based interaction capabilities and ensures robust testing and validation for seamless integration.

- **Fast_API Routes**:
  - Introduced `Routes__Json_Prompt` with endpoints for:
    - Summary creation
    - Document improvement
    - Summary validation
    - Email generation
    - Form generation
    - Graph extraction
    - Mermaid diagram generation

- **Prompt to JSON Framework**:
  - Extended `Prompt_To_Json__Open_AI` to support structured responses with enhanced metadata (e.g., duration, temperature, seed, timestamp).
  - Replaced `model` with `llm_model` for clarity.
  - Updated response parsing to include detailed metrics and response schemas.

- **Use Cases**:
  - Implemented specialized classes for JSON prompt scenarios:
    - `Json_Prompt__Create_Summary`
    - `Json_Prompt__Document_Improver`
    - `Json_Prompt__Email_Generator`
    - `Json_Prompt__Form_Generator`
    - `Json_Prompt__Graph_Extractor`
    - `Json_Prompt__Mermaid_Generator`
    - `Json_Prompt__Validate_Summary`

- **Integration Tests**:
  - Added integration tests for all new use cases with validation against expected behavior and edge cases.

- **Refactors and Cleanup**:
  - Refactored legacy `model` references in test cases and core logic.
  - Improved formatting
  - Added TODO comments for future improvements (e.g., replacing OpenAI client with a custom requests-based implementation for performance).

Author: DinisCruz

osbot_llms/fast_api/Fast_API_Route.py

@@ -2,7 +2,7 @@
 
 from osbot_utils.base_classes.Kwargs_To_Self import Kwargs_To_Self
 
-
+# todo: legacy replace with the new Fast_API_Routes
 class Fast_API__Routes(Kwargs_To_Self):
     router      : APIRouter
     path_prefix : str

osbot_llms/fast_api/Fast_API__LLMs.py

@@ -2,14 +2,16 @@
 from osbot_fast_api.api.Fast_API            import Fast_API
 from osbot_llms.fast_api.routes.Routes__Chat import Routes__Chat
 from osbot_llms.fast_api.routes.Routes__Info import Routes__Info
+from osbot_llms.fast_api.routes.Routes__Json_Prompt import Routes__Json_Prompt
 
 
 class Fast_API__LLMs(Fast_API):
     base_path  : str  = '/llms'
     enable_cors: bool = True
 
     def setup_routes(self):
-        self.add_routes(Routes__Chat)
-        self.add_routes(Routes__Info)
+        self.add_routes(Routes__Chat       )
+        self.add_routes(Routes__Info       )
+        self.add_routes(Routes__Json_Prompt)
 
 

osbot_llms/fast_api/routes/Routes__Json_Prompt.py

@@ -0,0 +1,122 @@
+from pydantic                                                                import BaseModel
+from osbot_fast_api.api.Fast_API_Routes                                      import Fast_API_Routes
+from typing import Optional, Dict, TypeVar, Type
+from osbot_llms.llms.prompt_to_json.use_cases.Json_Prompt__Create_Summary    import Model__Response_Format__Json_Prompt__Create_Summary, Json_Prompt__Create_Summary
+from osbot_llms.llms.prompt_to_json.use_cases.Json_Prompt__Document_Improver import Model__Response_Format__Json_Prompt__Document_Improver, Json_Prompt__Document_Improver
+from osbot_llms.llms.prompt_to_json.use_cases.Json_Prompt__Validate_Summary  import Model__Response_Format__Json_Prompt__Validate_Summary, Json_Prompt__Validate_Summary
+from osbot_llms.llms.prompt_to_json.use_cases.Json_Prompt__Email_Generator   import Model__Response_Format__Json_Prompt__Email_Generator, Json_Prompt__Email_Generator
+from osbot_llms.llms.prompt_to_json.use_cases.Json_Prompt__Form_Generator    import Model__Response_Format__Json_Prompt__Form_Generator, Json_Prompt__Form_Generator
+from osbot_llms.llms.prompt_to_json.use_cases.Json_Prompt__Graph_Extractor   import Model__Response_Format__Json_Prompt__Graph_Extractor, Json_Prompt__Graph_Extractor, GraphResponse
+from osbot_llms.llms.prompt_to_json.use_cases.Json_Prompt__Mermaid_Generator import Model__Response_Format__Json_Prompt__Mermaid_Generator, Json_Prompt__Mermaid_Generator
+from osbot_utils.helpers.Random_Guid import Random_Guid
+from osbot_utils.utils.Status import status_ok, status_error
+
+
+class Model__Fast_API__Create_Summary(BaseModel):
+    target_text: str
+
+class Model__Fast_API__Document_Improver(BaseModel):
+    current_content: str
+    improvement_request: str
+
+class Model__Fast_API__Validate_Summary(BaseModel):
+    original_text: str
+    summary: str
+
+class Model__Fast_API__Email_Generator(BaseModel):
+    email_requirements: str
+    context: Optional[Dict] = None
+
+class Model__Fast_API__Form_Generator(BaseModel):
+    form_requirements: str
+
+class Model__Fast_API__Graph_Extractor(BaseModel):
+    content: str
+
+class Model__Fast_API__Mermaid_Generator(BaseModel):
+    graph: GraphResponse
+    style_request: Optional[str] = ""
+
+
+class Routes__Json_Prompt(Fast_API_Routes):
+    tag : str = 'json-prompt'
+
+    def invoke_prompt(self, target_class: Type, target_method: str, method_kwargs) -> Dict:
+        try:
+            response = getattr(target_class(), target_method)(**method_kwargs)
+
+            data = { 'json_prompt_id' : Random_Guid()                 ,
+                     'duration'       : response.get('duration'       ),
+                     'llm_model'      : response.get('llm_model'      ),
+                     'response_json'  : response.get('response_json'  ),
+                     'response_schema': response.get('response_schema'),
+                     'seed'           : response.get('seed'           ),
+                     'temperature'    : response.get('temperature'    ),
+                     'timestamp'      : response.get('timestamp'      ),
+                     'tokens'         : response.get('tokens'         ),
+            }
+            return status_ok(message="Json Prompt created ok", data=data)
+        except Exception as exception:
+            return status_error(message="Failed to create Json Prompt", error=f'{exception}')
+
+    def create_summary(self, request: Model__Fast_API__Create_Summary):
+        target_class  = Json_Prompt__Create_Summary
+        target_method = 'create_summary'
+        target_kwargs = dict(target_text=request.target_text)
+        result        = self.invoke_prompt(target_class, target_method, target_kwargs)
+        return result
+
+    def improve_document(self, request: Model__Fast_API__Document_Improver):
+        target_class  = Json_Prompt__Document_Improver
+        target_method = 'improve_document'
+        target_kwargs = dict(current_content     = request.current_content,
+                             improvement_request = request.improvement_request)
+        result        = self.invoke_prompt(target_class, target_method, target_kwargs)
+        return result
+
+    def validate_summary(self, request: Model__Fast_API__Validate_Summary):
+        target_class  = Json_Prompt__Validate_Summary
+        target_method = 'validate_summary'
+        target_kwargs = dict(original_text = request.original_text,
+                             summary      = request.summary)
+        result        = self.invoke_prompt(target_class, target_method, target_kwargs)
+        return result
+
+    def generate_email(self, request: Model__Fast_API__Email_Generator):
+        target_class  = Json_Prompt__Email_Generator
+        target_method = 'generate_email'
+        target_kwargs = dict(email_requirements = request.email_requirements,
+                             context           = request.context)
+        result        = self.invoke_prompt(target_class, target_method, target_kwargs)
+        return result
+
+    def generate_form(self, request: Model__Fast_API__Form_Generator):
+        target_class  = Json_Prompt__Form_Generator
+        target_method = 'generate_form'
+        target_kwargs = dict(form_requirements = request.form_requirements)
+        result        = self.invoke_prompt(target_class, target_method, target_kwargs)
+        return result
+
+    def extract_graph(self, request: Model__Fast_API__Graph_Extractor):
+        target_class  = Json_Prompt__Graph_Extractor
+        target_method = 'extract_graph'
+        target_kwargs = dict(content = request.content)
+        result        = self.invoke_prompt(target_class, target_method, target_kwargs)
+        return result
+
+    def generate_mermaid(self, request: Model__Fast_API__Mermaid_Generator):
+        target_class  = Json_Prompt__Mermaid_Generator
+        target_method = 'convert_to_mermaid'
+        target_kwargs = dict(graph         = request.graph,
+                             style_request = request.style_request)
+        result        = self.invoke_prompt(target_class, target_method, target_kwargs)
+        return result
+
+    def setup_routes(self):
+        self.add_route_post(self.create_summary  )
+        self.add_route_post(self.improve_document)
+        self.add_route_post(self.validate_summary)
+        self.add_route_post(self.generate_email  )
+        self.add_route_post(self.generate_form   )
+        self.add_route_post(self.extract_graph   )
+        self.add_route_post(self.generate_mermaid)

osbot_llms/llms/prompt_to_json/Prompt_To_Json__Open_AI.py

@@ -1,18 +1,17 @@
 from typing import List, Dict
-
-import openai
-from pydantic import BaseModel
 from pydantic._internal._model_construction import ModelMetaclass
 
 from osbot_llms.llms.API_Open_AI import API_Open_AI
 from osbot_utils.base_classes.Type_Safe import Type_Safe
+from osbot_utils.context_managers.capture_duration import capture_duration
+from osbot_utils.helpers.Timestamp_Now import Timestamp_Now
 from osbot_utils.utils.Json import str_to_json
 
 
 class Prompt_To_Json__Open_AI(Type_Safe):
     response_format : ModelMetaclass
     messages        : List[Dict[str, str]]
-    model           : str
+    llm_model       : str
     temperature     : float
     seed            : int
 
@@ -30,37 +29,24 @@ def add_message(self,role, content):
         return self
 
     def invoke(self):
-        response        = self.invoke__raw()
-        response_parsed = self.parse_response(response)
+        with capture_duration() as duration:
+            response        = self.invoke__raw()
+        response_parsed = self.parse_response(response, duration.seconds)
         return response_parsed
 
     def invoke__raw(self):
-        client = API_Open_AI().client()
-
-        try:
-            completion = client.beta.chat.completions.parse(**self.invoke_kwargs())
-            return completion
-        except Exception as exception:                  # todo: figure out the exceptions to handle here
-            raise exception
-            # # Handle edge cases
-            # if type(e) == openai.LengthFinishReasonError:
-            #     # Retry with a higher max tokens
-            #     print("Too many tokens: ", e)
-            #     pass
-            # else:
-            #     # Handle other exceptions
-            #     print(e)
-            #     pass
+        client = API_Open_AI().client()                                     # todo replace this with requests api (and see the performance implications of creating this object all the time, for example see if there are advantages in caching the requests session)
+        return  client.beta.chat.completions.parse(**self.invoke_kwargs())
 
     def invoke_kwargs(self):
-        return dict(model           = self.model          ,
+        return dict(model           = self.llm_model      ,
                     messages        = self.messages       ,
                     response_format = self.response_format,
                     seed            = self.seed           ,
                     temperature     =self.temperature     )
 
     def set_model(self, model):
-        self.model = model
+        self.llm_model = model
         return self
 
     def set_model__gpt_4o(self):
@@ -73,13 +59,19 @@ def set_response_format(self, response_format):
         self.response_format = response_format
         return self
 
-    def parse_response(self, response):
-        choice  = response.choices[0]
-        message = choice.message
-        usage   = response.usage
-        content = str_to_json(message.content)
-        model   = message.parsed
-        tokens  = usage.total_tokens
-        return dict(content = content,
-                    model   = model  ,
-                    tokens  = tokens )
+    def parse_response(self, response, duration):
+        choice          = response.choices[0]
+        message         = choice.message
+        usage           = response.usage
+        response_json   = str_to_json(message.content)
+        response_parsed = message.parsed
+        tokens          = usage.total_tokens
+        return dict(response_json   = response_json                ,
+                    response_parsed = response_parsed              ,
+                    duration        = duration                     ,
+                    llm_model       = self.llm_model               ,
+                    response_schema = self.response_format.__name__,
+                    seed            = self.seed                    ,
+                    temperature     = self.temperature             ,
+                    timestamp       = Timestamp_Now()              ,
+                    tokens          = tokens                       )

osbot_llms/llms/prompt_to_json/use_cases/Json_Prompt__Create_Summary.py

@@ -1,7 +1,6 @@
-from pydantic import BaseModel
-
+from pydantic                                               import BaseModel
 from osbot_llms.llms.prompt_to_json.Prompt_To_Json__Open_AI import Prompt_To_Json__Open_AI
-from osbot_utils.base_classes.Type_Safe import Type_Safe
+from osbot_utils.base_classes.Type_Safe                     import Type_Safe
 
 
 class Model__Response_Format__Json_Prompt__Create_Summary(BaseModel):

osbot_llms/llms/prompt_to_json/use_cases/Json_Prompt__Document_Improver.py

@@ -0,0 +1,65 @@
+from pydantic                                               import BaseModel
+from typing                                                 import List, Literal
+from osbot_llms.llms.prompt_to_json.Prompt_To_Json__Open_AI import Prompt_To_Json__Open_AI
+from osbot_utils.base_classes.Type_Safe                     import Type_Safe
+
+class DocumentChange(BaseModel):
+    type    : Literal['addition', 'deletion', 'addition', 'formatting']
+    original: str
+    updated : str
+    reason  : str
+
+class DocumentResponse(BaseModel):
+    new_version: str
+    changes    : List[DocumentChange]
+    summary    : str
+
+class Model__Response_Format__Json_Prompt__Document_Improver(BaseModel):
+    document: DocumentResponse
+    status  : Literal['success', 'error', 'partial_success', 'no_changes_needed', 'validation_failed']
+
+
+class Json_Prompt__Document_Improver(Type_Safe):
+    prompt_to_json: Prompt_To_Json__Open_AI
+    response_format: type = None
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.response_format = Model__Response_Format__Json_Prompt__Document_Improver
+
+    def improve_document(self, current_content: str, improvement_request: str):
+        with self.prompt_to_json as _:
+            _.set_model__gpt_4o_mini()
+            _.set_response_format(self.response_format)
+            _.add_message__system(self.system_prompt())
+            _.add_message__user(f"""\
+
+-------------  Current document content: -------------
+{current_content}
+------------------------------------------------------
+
+-------------  Improvement request:      -------------
+
+{improvement_request}
+
+------------------------------------------------------""")
+            return _.invoke()
+
+    def system_prompt(self):
+        return """You are a document improvement assistant. Follow these rules exactly:
+
+1. Preserve document structure and formatting
+2. Maintain key information integrity
+3. Keep consistent writing style
+5. Only make requested improvements
+6. Provide clear reasoning for changes
+
+For each change:
+- Include original and modified text
+- Explain modification rationale
+
+Return a structured response with:
+- Complete updated document
+- Detailed change log
+- Change summary
+- Status indicator"""