PyAres 1.0.1__tar.gz → 1.2.0__tar.gz

{pyares-1.0.1 → pyares-1.2.0}/.gitignore

@@ -168,6 +168,7 @@ cython_debug/
 
 # VS Code
 .vscode/
+.vs/
 
 #macOS
 .DS_Store

pyares-1.2.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: PyAres
+Version: 1.2.0
+Summary: The official Python library for ARES.
+Project-URL: Homepage, https://github.com/AFRL-ARES/PyAres
+Author-email: AFRL <AFRL.RX.AREScontact@us.af.mil>
+License: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: ares-datamodel>=0.31.0
+Description-Content-Type: text/markdown
+
+# PyAres
+
+The PyAres library is designed to provide support for building planners, analyzers and devices as part of your ARES self driving labratory. PyAres leverages the power of protobuf and gRPC to communicate with your ARES system while providing a simple Pythonic API.
+
+You can find the main documentation on PyAres [here](https://afrl-ares.github.io/docs/pyares/intro) as well as the rest of the ARES ecosystem by visting https://afrl-ares.github.io/ to browse our centralized documentation site.
+
+### 📄 License
+
+The PyAres project is licensed under the MIT License - see details in [LICENSE.txt]([https://github.com/AFRL-ARES/PyAres/blob/Develop/LICENSE.txt](https://github.com/AFRL-ARES/PyAres/blob/Develop/LICENSE)) <br></br>
+
+### CLEARANCE
+
+Distribution A. Approved for public release: distribution unlimited. AFRL-2025-5332.

pyares-1.2.0/PyAres/Analyzing/analysis_service.py

@@ -0,0 +1,147 @@
+# Standard Imports
+import grpc
+from typing import Callable, Awaitable, Union, Mapping, Dict, Optional
+
+# Import generated protobuf and gRPC stubs
+from ares_datamodel.analyzing.remote import ares_remote_analyzer_service_pb2 as analyzer_service
+from ares_datamodel.analyzing.remote import ares_remote_analyzer_service_pb2_grpc as analyzer_service_grpc
+from ares_datamodel.analyzing import analysis_pb2
+from ares_datamodel.analyzing import analyzer_capabilities_pb2
+from ares_datamodel import ares_data_schema_pb2
+from ares_datamodel import ares_outcome_enum_pb2
+
+# Import Utilities
+from ..Utils import ares_struct_utils
+from ..Utils import ares_data_schema_utils
+from ..Utils import ares_outcome_utils
+from ..Utils.ares_service_base import AresServiceWrapperBase, AresBaseService
+
+# Import python models
+from ..Models import ares_data_models, RequestMetadata, AresSchemaEntry
+from .analyzer_models import AnalysisRequest, AnalysisResponse
+
+# Type hints for the user's custom logic
+AnalyzeLogicFunction = Callable[[AnalysisRequest], Union[AnalysisResponse, Awaitable[AnalysisResponse]]]
+
+class AresAnalyzerServiceWrapper(AresServiceWrapperBase, analyzer_service_grpc.AresRemoteAnalyzerServiceServicer):
+    """
+    A wrapper around the gRPC service to expose native Python objects for analysis.
+    """
+    def __init__(self, name: str, version: str, description: str, timeout: int, custom_analysis_logic: AnalyzeLogicFunction):
+        super().__init__(name, version, description, timeout)
+        self._custom_analysis_logic = custom_analysis_logic
+        self._analysis_parameters: Dict[str, ares_data_schema_pb2.AresValueSchema] = {}
+
+    def Analyze(self, request: analyzer_service.AnalysisRequest, context) -> analysis_pb2.Analysis:
+        print("Received an analysis request!")
+        try:
+            python_request = AnalysisRequest(
+                inputs=ares_struct_utils.ares_struct_to_dict(request.inputs),
+                settings=ares_struct_utils.ares_struct_to_dict(request.settings),
+                metadata=RequestMetadata(request.metadata))
+
+            python_response = self._custom_analysis_logic(python_request)
+            python_response = self._resolve_awaitable(python_response)
+
+            if not isinstance(python_response, AnalysisResponse):
+                print("Analysis response was an invalid type, ")
+                proto_analysis = analysis_pb2.Analysis()
+                proto_analysis.analysis_outcome = ares_outcome_enum_pb2.FAILURE
+                proto_analysis.error_string = "The user's custom analysis logic returned an invalid type, analysis cannot be processed"
+                return proto_analysis
+            
+            print("Sending Analysis Response.....")
+            return analysis_pb2.Analysis(
+                result=python_response.result,
+                analysis_outcome=ares_outcome_utils.python_ares_outcome_to_proto_ares_outcome(python_response.outcome),
+                error_string=python_response.error_string
+            )
+        
+        except Exception as e:
+            context.set_code(grpc.StatusCode.INTERNAL)
+            context.set_details(f"Error in custom analysis logic: {e}")
+            return analysis_pb2.Analysis(analysis_outcome=ares_outcome_enum_pb2.FAILURE, error_string=str(e))
+
+
+    def GetAnalysisParameters(self, request, context):
+        print("Analysis Parameters Requested")
+        try:
+            analysisParamResponse = analyzer_service.AnalysisParametersResponse()
+
+            for key, value in self._analysis_parameters.items():
+                map_entry = analysisParamResponse.parameter_schema.fields[key]
+                map_entry.CopyFrom(value)
+
+            return analysisParamResponse
+    
+        except Exception as e:
+            print(f"Exception while trying to respond to ARES with analysis parameters! {e}")
+
+    def GetAnalyzerCapabilities(self, request, context) -> analyzer_capabilities_pb2.AnalyzerCapabilities:
+        print("Capabilities Requested!")
+        capabilities = analyzer_capabilities_pb2.AnalyzerCapabilities(timeout_seconds=self._timeout)
+        try:
+            for(key, value) in self._settings.items():
+                settings_entry = capabilities.settings_schema.fields[key]
+                settings_entry.CopyFrom(value)
+            
+            return capabilities
+
+        except Exception as e:
+            print(f"Exception while trying to respond to ARES capabilities request! {e}") 
+            return capabilities
+        
+
+    def ValidateInputs(self, request: analyzer_service.ParameterValidationRequest, context): 
+        response = analyzer_service.ParameterValidationResult(success=True)
+        provided_params: Mapping[str, ares_data_schema_pb2.AresValueSchema] = request.input_schema.fields
+
+        for stored_key, stored_schema in self._analysis_parameters.items():
+            if stored_key in provided_params:
+                matching_schema = provided_params[stored_key]
+                if stored_schema.type != matching_schema.type:
+                    message = f"Schema Mismatch! {stored_key} was provided with the value type {stored_schema.type}, but the value type {matching_schema} was expected!"
+                    response.messages.append(message)
+            else:
+                if not stored_schema.optional:
+                    message = f"Schema Missing! {stored_key} is marked as a required piece of data for analysis, but no assignment was found in the provided schema!"
+                    response.messages.append(message)
+
+        if len(response.messages) != 0:
+            response.success = False
+
+        return response
+ 
+class AresAnalyzerService(AresBaseService):
+    """
+    Manages the gRPC server for the AresAnalyzerService.
+    """
+    def __init__(self,
+                 custom_analysis_logic: AnalyzeLogicFunction,
+                 name: str,
+                 version: str,
+                 description: str = "",
+                 timeout: int = 30,
+                 use_localhost: bool = True,
+                 port: int = 7083,
+                 max_message_size: int = -1):
+        """
+        Initializes the AresAnalyzerService.
+        """
+        super().__init__(
+            service_name=name,
+            description=description,
+            version=version,
+            port=port,
+            use_localhost=use_localhost,
+            max_message_size=max_message_size
+        )
+
+        self._service_wrapper = AresAnalyzerServiceWrapper(name=name, version=version, description=description, timeout=timeout, custom_analysis_logic=custom_analysis_logic)
+        analyzer_service_grpc.add_AresRemoteAnalyzerServiceServicer_to_server(self._service_wrapper, self.get_server())
+
+    def add_analysis_parameter(self, parameter_name: str, parameter_type: ares_data_models.AresDataType, optional: bool = False, struct_schema: Optional[Dict[str, AresSchemaEntry]] = None):
+        """
+        Adds an analysis parameter that will be reported to ARES.
+        """
+        self._service_wrapper._analysis_parameters[parameter_name] = ares_data_schema_utils.create_settings_schema_entry(parameter_type, optional, [], struct_schema)

{pyares-1.0.1 → pyares-1.2.0}/PyAres/Demo/Devices/device_test.py

@@ -30,7 +30,7 @@ if __name__ == "__main__":
   device_name = "Demo Device"
   description = "A device to demonstrate the PyAres device capabilities"
   version = "1.0.0"
-  device_service = AresDeviceService(device.enter_safe_mode, device.get_device_state, device_name, description, version)
+  device_service = AresDeviceService(device.enter_safe_mode, device.get_device_state, device_name, description, version, False)
 
   # Create the "Set Temperature" Command
   quantity_schema = QuantitySchema(ureg.degree_Celsius, 40.0, 125.0)
@@ -40,7 +40,7 @@ if __name__ == "__main__":
   device_service.add_new_command(set_temp_descriptor, device.set_temperature)
 
   # Create the "Get Temperature" Command
-  output_schema = {"temperature": DeviceSchemaEntry(AresDataType.QUANTITY, "The current temperature of the device", quantity_schema=quantity_schema)}
+  output_schema = {"temperature": DeviceSchemaEntry(AresDataType.NUMBER, "The current temperature of the device")}
   get_temp_desc = DeviceCommandDescriptor("Get Temperature", "Get's the current temperature of the demo device.", {}, output_schema)
   device_service.add_new_command(get_temp_desc, device.get_temperature)
 

{pyares-1.0.1 → pyares-1.2.0}/PyAres/Demo/Planners/planner_test.py

@@ -8,6 +8,14 @@ def plan(request: PlanRequest) -> PlanResponse:
   gpdoods = []
   names = []
 
+  for i in range(len(request.analysis_results)):
+    currentAnalysis = request.analysis_results[i]
+
+    for j in range(len(currentAnalysis.objectives)):
+      currentObjective : Objective = currentAnalysis.objectives[j]
+      print(f"Analysis Result {i}: Objective number {j} is named {currentObjective.objective_name} and has a value of {currentObjective.objective_value}")
+
+    
   for param in request.parameters:
     if param.planner_name == "GPRDood":
       gpdoods.append(param)

pyares-1.2.0/PyAres/Demo/Planners/planner_wiki.py

@@ -0,0 +1,33 @@
+from PyAres import *
+from typing import List
+import random
+
+def generate_plans(request: PlanRequest) -> List[Plan]:    
+    plans = []
+    for i in request.previous_plan_status_codes:
+        print(f"Status Code: {i}")
+
+    # Make as many plans as was requested
+    for i in range(request.batch_size):
+        current_params = []
+        for param in request.parameters:
+            # Simple Logic: Pick a random value within the allowed range
+            val = random.uniform(param.minimum_value, param.maximum_value)
+            current_params.append(PlannedParameter(param.name, val))
+        
+        plans.append(Plan(current_params, Outcome.SUCCESS))
+
+    return plans
+
+if __name__ == "__main__":
+    service = AresPlannerService(
+        generate_plans, 
+        "Random Search Planner", 
+        "This planner picks random values within bounds.", 
+        "1.0.0"
+    )
+
+    # Tell ARES we can plan for Numeric values
+    service.add_supported_type(AresDataType.NUMBER)
+
+    service.start()

{pyares-1.0.1 → pyares-1.2.0}/PyAres/Device/device_service.py

@@ -2,7 +2,6 @@ import grpc
 import inspect
 import time
 import warnings
-from concurrent import futures
 from typing import Dict, Callable, Awaitable, Union, Any, Optional
 
 from ares_datamodel.device.remote import ares_remote_device_service_pb2 as device_service
@@ -16,13 +15,14 @@ from google.protobuf import empty_pb2
 
 from .device_models import DeviceCommandDescriptor
 from ..Models import Limits
-from .device_models import DeviceCommandDescriptor, DeviceCommandResponse, StatusCode
+from .device_models import DeviceCommandDescriptor, DeviceCommandResponse
 from ..Utils import ares_device_command_utils
 from ..Utils import ares_data_schema_utils
 from ..Utils import ares_struct_utils
 from ..Utils import ares_value_utils
 from ..Utils import ares_data_type_utils
 from ..Utils import device_status_code_utils
+from ..Utils.ares_service_base import AresServiceWrapperBase, AresBaseService
 
 # Type hint for the user's custom methods
 EnterSafeModeMethod = Callable[[], None]
@@ -30,15 +30,19 @@ AllowedReturns = Union[DeviceCommandResponse, Dict[str, Any], Any]
 DeviceCommandMethod = Callable[..., AllowedReturns]
 DeviceStateMethod = Callable[[], Dict[str, Any]]
 
-class AresDeviceServiceWrapper(device_service_grpc.AresRemoteDeviceServiceServicer):
+class AresDeviceServiceWrapper(AresServiceWrapperBase, device_service_grpc.AresRemoteDeviceServiceServicer):
   """
   A wrapper around the gRPC service to expose native Python objects for devices
   """
 
-  def __init__(self, device_name: str, description: str, version: str, enter_safe_mode: EnterSafeModeMethod, update_device_state: DeviceStateMethod):
+  def __init__(self, device_name: str, description: str, version: str, timeout: int, enter_safe_mode: EnterSafeModeMethod, update_device_state: DeviceStateMethod):
+    super().__init__(service_name=device_name, version=version, description=description, timeout=timeout)
+
+    # Preserve public attributes for backwards compatibility
     self.device_name = device_name
     self.description = description
     self.version = version
+
     self._enter_safe_mode = enter_safe_mode
     self._update_device_state = update_device_state
     self._setting_schema: Dict[str, ares_data_schema_pb2.AresValueSchema] = {}
@@ -48,13 +52,16 @@ class AresDeviceServiceWrapper(device_service_grpc.AresRemoteDeviceServiceServic
     self._command_methods: Dict[str, Callable] = {}
 
   def GetOperationalStatus(self, request, context) -> device_status_pb2.DeviceOperationalStatus:
-    return device_status_pb2.DeviceOperationalStatus(operational_state=device_status_pb2.OperationalState.ACTIVE, message=f"{self.device_name} is active!")
+    return device_status_pb2.DeviceOperationalStatus(
+      operational_state=device_status_pb2.OperationalState.ACTIVE,
+      message=f"{self._service_name} is active!"
+    )
 
   def GetInfo(self, request, context) -> device_service.DeviceInfoResponse:
     info = device_service.DeviceInfoResponse()
-    info.name = self.device_name
-    info.description = self.description
-    info.version = self.version
+    info.name = self._service_name
+    info.description = self._description
+    info.version = self._version
     return info
   
   def GetCommands(self, request, context) -> device_service.CommandsResponse:
@@ -249,7 +256,7 @@ class AresDeviceServiceWrapper(device_service_grpc.AresRemoteDeviceServiceServic
     except grpc.RpcError as e:
       print(f"gRPC error occured in device state stream")
 
-class AresDeviceService:
+class AresDeviceService(AresBaseService):
   """ Manages the gRPC service for the AresDeviceSerivce """
   def __init__(self, 
                enter_safe_mode_logic: EnterSafeModeMethod, 
@@ -257,8 +264,10 @@ class AresDeviceService:
                device_name: str,
                description: str, 
                version: str, 
+               timeout: int = 30,
                use_localhost: bool = True, 
-               port: int = 7100):
+               port: int = 7100,
+               max_message_size: int = -1):
     """
     Initializes the AresDeviceService
     
@@ -270,22 +279,28 @@ class AresDeviceService:
       device_name (str): The name description of your device.
       description (str): A brief description of your device.
       version (str): The version associated with your device implementation.
+      timeout (int): Timeout in seconds for service calls reported to ARES.
       use_localhost (bool): An optional value that allows the user to specify whether to host the service on the local network. Defaults to True.
       port (int): The port that your device service will serve on. Defaults to port 7100.
+      max_message_size (int): Maximum message size for gRPC. Defaults to -1 (use library default).
     """
 
+    super().__init__(
+      service_name=device_name,
+      description=description,
+      version=version,
+      port=port,
+      use_localhost=use_localhost,
+      max_message_size=max_message_size
+    )
+
+    # Preserve these public attributes for backwards compatibility
     self.device_name = device_name
     self.description = description
     self.version = version
 
-    self._port = port
-    self._server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
-    self._service_wrapper = AresDeviceServiceWrapper(device_name, description, version, enter_safe_mode_logic, get_device_state_logic)
-    device_service_grpc.add_AresRemoteDeviceServiceServicer_to_server(self._service_wrapper, self._server)
-    if(use_localhost):
-      self._server.add_insecure_port(f'localhost:{self._port}')
-    else:
-      self._server.add_insecure_port(f'[::]:{self._port}')
+    self._service_wrapper = AresDeviceServiceWrapper(device_name, description, version, timeout, enter_safe_mode_logic, get_device_state_logic)
+    device_service_grpc.add_AresRemoteDeviceServiceServicer_to_server(self._service_wrapper, self.get_server())
 
   def add_new_command(self, cmd_descriptor: DeviceCommandDescriptor, method):
     """
@@ -345,12 +360,13 @@ class AresDeviceService:
     """
 
     print(f"Starting Ares Device Service on port {self._port}...")
-    self._server.start()
+    server = self.get_server()
+    server.start()
 
     if wait_for_termination:
-      self._server.wait_for_termination()
+      server.wait_for_termination()
 
   def stop(self):
     """ Stops the service, terminating the connection. """
     print("Stopping Ares Device Service...")
-    self._server.stop(0).wait()    
+    self.get_server().stop(0).wait()    

{pyares-1.0.1 → pyares-1.2.0}/PyAres/Models/__init__.py

@@ -1,4 +1,4 @@
-from .ares_data_models import AresDataType, Outcome, RequestMetadata, AresSchemaEntry, Quantity, QuantitySchema, Limits
+from .ares_data_models import AresDataType, Outcome, RequestMetadata, AresSchemaEntry, Quantity, QuantitySchema, Limits, PlanStatusCode
 
 __all__ = [
     "AresDataType",
@@ -7,5 +7,6 @@ __all__ = [
     "AresSchemaEntry",
     "Quantity",
     "QuantitySchema",
-    "Limits"
+    "Limits",
+    "PlanStatusCode"
 ]

{pyares-1.0.1 → pyares-1.2.0}/PyAres/Models/ares_data_models.py

@@ -30,6 +30,12 @@ class Outcome(Enum):
     WARNING = 3
     CANCELED = 4
 
+class PlanStatusCode(Enum):
+    PLAN_STATUS_UNSPECIFIED = 0
+    PLAN_ACCEPTED = 1
+    PLAN_UNACHIEVABLE = 2
+    PLAN_FAILED = 3
+
 class RequestMetadata():
     def __init__(self, proto_metadata: request_metadata_pb2.RequestMetadata):
         self.system_name = proto_metadata.system_name

{pyares-1.0.1 → pyares-1.2.0}/PyAres/Planning/__init__.py

@@ -1,9 +1,13 @@
-from .planner_models import PlanningParameter, PlanRequest, PlanResponse, ParameterHistoryItem
+from .planner_models import PlanningParameter, PlanRequest, PlanResponse, ParameterHistoryItem, Plan, PlannedParameter, ObjectiveStatus
 from .planning_service import AresPlannerService
 
 __all__ = [
     "PlanningParameter",
     "PlanRequest",
     "PlanResponse",
-    "AresPlannerService"
+    "AresPlannerService",
+    "Plan",
+    "PlannedParameter",
+    "ParameterHistoryItem",
+    "ObjectiveStatus"
 ]

{pyares-1.0.1 → pyares-1.2.0}/PyAres/Planning/planner_models.py

@@ -1,5 +1,6 @@
 from typing import Dict, Any, List, Sequence, Optional
-from ..Models import Outcome, AresDataType, RequestMetadata
+from ..Models import Outcome, AresDataType, RequestMetadata, PlanStatusCode
+from enum import Enum
 
 class ParameterHistoryItem:
     """ Represents a single historical parameter item """
@@ -20,6 +21,13 @@ class ParameterHistoryItem:
     
     def __repr__(self) -> str:
         return self.__str__()
+    
+class ObjectiveStatus(Enum):
+    """ An enum representing the current status of the objective the planner is trying to achieve (if any) """
+    OBJECTIVE_STATUS_UNSPECIFIED = 0
+    OBJECTIVE_UNACHIEVED = 1
+    OBJECTIVE_ACHIEVED = 2
+    OBJECTIVE_FAILED = 3
 
 class PlanningParameter:
     """
@@ -28,9 +36,15 @@ class PlanningParameter:
     Designed to provide a more user-friendly abstraction for the user to interact
     with planning parameters through.
     """
-    def __init__(self, name: str, minimum_value: float, 
-                 maximum_value: float, param_history: list[ParameterHistoryItem], data_type: AresDataType, 
-                 is_planned: bool, is_result: bool, planner_name: str, initial_value = None):
+    def __init__(self, name: str, 
+                 data_type: AresDataType,
+                 minimum_value: float = None, 
+                 maximum_value: float = None, 
+                 param_history: list[ParameterHistoryItem] = [],
+                 is_planned: bool = False, 
+                 is_result: bool = False, 
+                 planner_name: str = "", 
+                 initial_value = None):
         """
         Initializes a PlanningParameter.
 
@@ -107,7 +121,13 @@ class PlanRequest:
     
     Designed to provide a more user-friendly abstraction for interacting with a plan request message.
     """
-    def __init__(self, parameters: list[PlanningParameter], settings: Dict[str, Any], analysis_results: Sequence[float], metadata: RequestMetadata = RequestMetadata.from_default_values()):
+    def __init__(self, 
+                parameters: list[PlanningParameter], 
+                settings: Dict[str, Any], 
+                analysis_results: Sequence[float],
+                metadata: RequestMetadata = RequestMetadata.from_default_values(),
+                batch_size: int = 1,
+                previous_plan_status_codes: List[PlanStatusCode] = None):
         """
         Initializes a PlanRequest.
 
@@ -117,8 +137,14 @@ class PlanRequest:
         self.parameters = parameters
         self.settings = settings
         self.analysis_results = analysis_results
+        self.batch_size = batch_size
         self.request_metadata = metadata
 
+        if previous_plan_status_codes is None:
+            self.previous_plan_status_codes = []
+        else:    
+            self.previous_plan_status_codes = previous_plan_status_codes
+
     def __str__(self) -> str:
         param_str = "\n ".join(self.parameter_names)
         settings_str = "\n ".join([f"{k}: {v}" for k, v in self.settings.items()])
@@ -127,13 +153,15 @@ class PlanRequest:
         metadata_str = str(self.request_metadata).replace('\n', '\n ')
         return (f"PlanRequest object with:\n"
                 f"parameters:\n"
-                f" {param_str}\n"
+                f"{param_str}\n"
                 f"settings:\n"
-                f" {settings_str}\n"
+                f"{settings_str}\n"
                 f"analysis_results:\n"
-                f" {analysis_str}\n"
+                f"{analysis_str}\n"
                 f"request_metadata:\n"
-                f"{metadata_str}")
+                f"{metadata_str}"
+                f"batch_size:\n"
+                f"{self.batch_size}")
     
     def __repr__(self) -> str:
         return self.__str__()
@@ -167,7 +195,8 @@ class PlanResponse:
                  parameter_values: Optional[list] = None,
                  parameter_data: Optional[dict[str,Any]] = None,
                  outcome: Outcome = Outcome.SUCCESS, 
-                 error_string: str = ""):
+                 error_string: str = "",
+                 objective_status: ObjectiveStatus = ObjectiveStatus.OBJECTIVE_STATUS_UNSPECIFIED):
         """
         Initializes a PlanResponse. Using either lists of names and values or a python dictonary of name:value pairs
 
@@ -175,6 +204,9 @@ class PlanResponse:
             parameter_names: A list of names associated with planned parameters.
             parameter_values: A list of values associated with planned parameters. 
             parameter_data: A python dictionary of key:value pairs of planned parameters and planned values
+            outcome: An enum of type Outcome that determines whether the planning process succeeded or not, defaults to SUCCESS
+            error_string: An optional string for specifying planning failure reasons to be relayed to ARES
+            objective_status: An optional value that specifies the status of the objective your planner is trying to achieve (if any)
         """
         if parameter_data is not None:
             self.parameter_names = list(parameter_data.keys())
@@ -191,13 +223,55 @@ class PlanResponse:
         
         self.outcome = outcome
         self.error_string = error_string
+        self.objective_status = objective_status
     
     def __str__(self):
         return (f"PlanResponse object with:\n"
                 f" outcome: {self.outcome}\n"
                 f" parameter_names: {self.parameter_names}\n"
                 f" parameter_values: {self.parameter_values}\n"
-                f" error_string: {self.error_string}\n")
+                f" error_string: {self.error_string}\n"
+                f" objective_status: {self.objective_status}\n")
     
     def __repr__(self) -> str:
-        return self.__str__()
+        return self.__str__()
+
+class PlannedParameter:
+    def __init__(self, parameter_name: str, parameter_value: Any):
+        self.parameter_name = parameter_name
+        self.parameter_value = parameter_value
+
+    def __str__(self):
+        # A clean, readable key-value output
+        return f"{self.parameter_name}: {self.parameter_value}"
+
+    def __repr__(self):
+        # The !r formatting flag automatically wraps strings in quotes and calls __repr__ on the values
+        return f"PlannedParameters(parameter_name={self.parameter_name!r}, parameter_value={self.parameter_value!r})"
+
+class Plan:
+    def __init__(self, 
+                 planned_parameters: List[PlannedParameter], 
+                 outcome: Outcome, 
+                 error_string: str = "", 
+                 objective_status: ObjectiveStatus = ObjectiveStatus.OBJECTIVE_STATUS_UNSPECIFIED):
+        self.planned_parameters = planned_parameters
+        self.outcome = outcome
+        self.error_string = error_string
+        self.objective_status = objective_status
+
+    def __str__(self):
+        base_str = f"Plan (Outcome: {self.outcome}) \n (Objective Status: {self.objective_status})"
+        
+        # Format the list of parameters into a readable string
+        if self.planned_parameters:
+            params_str = ", ".join(str(p) for p in self.planned_parameters)
+            base_str += f" | Parameters: [{params_str}]"
+            
+        if self.error_string:
+            base_str += f" - Error: '{self.error_string}'"
+            
+        return base_str
+
+    def __repr__(self):
+        return f"Plan(planned_parameters={self.planned_parameters!r}, outcome={self.outcome!r}, error_string={self.error_string!r})"