aitomatic · nguyennm1024 · Oct 23, 2024 · Oct 20, 2024 · Oct 20, 2024 · Oct 20, 2024
diff --git a/examples/llamarine/.env.template b/examples/llamarine/.env.template
@@ -0,0 +1 @@
+OPENAI_API_KEY=
diff --git a/examples/llamarine/Makefile b/examples/llamarine/Makefile
@@ -0,0 +1,2 @@
+streamlit-run:
+	@poetry run streamlit run streamlit-main.py --server.allowRunOnSave=true --server.runOnSave=true
diff --git a/examples/llamarine/README.md b/examples/llamarine/README.md
@@ -0,0 +1,7 @@
+<!-- markdownlint-disable MD043 -->
+
+# Maritime-Specific Agents leveraging Open-Source `Llamarine` LM
+
+## Streamlit App
+
+Run by `make streamlit-run`
diff --git a/examples/llamarine/agent.py b/examples/llamarine/agent.py
@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+from functools import cache
+
+from openssa import Agent, ProgramSpace, HTP, HTPlanner, OpenAILM
+
+# pylint: disable=wrong-import-order
+from data_and_knowledge import EXPERT_PROGRAM_SPACE, EXPERT_KNOWLEDGE
+
+
+@cache
+def get_or_create_agent(max_depth=2, max_subtasks_per_decomp=4) -> Agent:
+    lm = OpenAILM.from_defaults()
+
+    program_space = ProgramSpace(lm=lm)
+    if EXPERT_PROGRAM_SPACE:
+        for program_name, htp_dict in EXPERT_PROGRAM_SPACE.items():
+            htp = HTP.from_dict(htp_dict)
+            program_space.add_or_update_program(name=program_name, description=htp.task.ask, program=htp)
+
+    return Agent(program_space=program_space,
+                 programmer=HTPlanner(lm=lm, max_depth=max_depth, max_subtasks_per_decomp=max_subtasks_per_decomp),
+                 knowledge={EXPERT_KNOWLEDGE} if EXPERT_KNOWLEDGE else None,
+                 resources={})
+
+
+if __name__ == '__main__':
+    arg_parser = ArgumentParser()
+    arg_parser.add_argument('problem')
+    args = arg_parser.parse_args()
+
+    print(get_or_create_agent().solve(problem=args.problem))
diff --git a/examples/llamarine/data_and_knowledge.py b/examples/llamarine/data_and_knowledge.py
@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from dotenv import load_dotenv
+import yaml
+
+if TYPE_CHECKING:
+    from openssa.core.programming.hierarchical.plan import HTPDict
+
+
+load_dotenv()
+
+
+EXPERT_KNOWLEDGE_FILE_PATH: Path = Path(__file__).parent / 'expert-knowledge.txt'
+with open(file=EXPERT_KNOWLEDGE_FILE_PATH,
+          buffering=-1,
+          encoding='utf-8',
+          errors='strict',
+          newline=None,
+          closefd=True,
+          opener=None) as f:
+    EXPERT_KNOWLEDGE: str = f.read()
+
+
+EXPERT_PROGRAM_SPACE_FILE_PATH: Path = Path(__file__).parent / 'expert-program-space.yml'
+with open(file=EXPERT_PROGRAM_SPACE_FILE_PATH,
+          buffering=-1,
+          encoding='utf-8',
+          errors='strict',
+          newline=None,
+          closefd=True,
+          opener=None) as f:
+    EXPERT_PROGRAM_SPACE: dict[str, HTPDict] = yaml.safe_load(stream=f)
diff --git a/examples/llamarine/expert-knowledge.txt b/examples/llamarine/expert-knowledge.txt
@@ -0,0 +1,159 @@
+SOG based on the Earth as the reference, might lead to misleading on radar such as display head on situation on the water 
+as crossing situation.
+STW based on water might avoid this ambiguty.
+
+Be careful with the risk misleading on radar such as display head on situation on the water as crossing situation.
+COLREGS was designed to all vessel, even without radar.
+
+# **Comprehensive and Technical Rule of Thumb for OOW Decision-Making with Focus on COLREGs**
+
+---
+
+## **1. General Watchkeeping Rules**  
+1. **“If you’re not looking, you’re not navigating.”**  
+   - Constantly scan the horizon and monitor instruments; **complacency kills safety**.  
+   - Set a **visual sweep cycle every 5-10 minutes**, especially in busy waters.
+
+2. **"Trust your eyes, confirm with instruments."**  
+   - Visual observations are primary—radar and AIS are support tools. **Don’t rely on AIS alone for collision avoidance.**
+
+3. **“If unsure, act early and decisively.”**  
+   - Uncertainty should trigger **immediate action**—reduce speed or change course to avoid developing a risky situation.
+
+---
+
+## **2. Mastering COLREGs Application**  
+1. **“When in doubt, give way—always.”**  
+   - If you cannot assess risk or priority clearly, **assume the give-way role** to stay safe.
+
+2. **“Clear and early course alterations save lives.”**  
+   - Make **large, unambiguous changes** in course or speed—others must know your intentions clearly.
+
+3. **"Stand-on means stay alert.”**  
+   - Even as the stand-on vessel, **be ready to act** if the give-way vessel fails to maneuver. Monitor closely (Rule 17).
+
+4. **"Always turn to starboard unless there’s a reason not to.”**  
+   - Meeting head-on? **Starboard turn is default** (Rule 14). Avoid left-turning unless absolutely necessary.
+
+5. **"You’re overtaking? You must stay clear."**  
+   - If approaching a vessel from more than 22.5° abaft the beam (Rule 13), **you are overtaking**—stay clear until the maneuver is complete.
+
+---
+
+## **3. Risk Assessment and Avoiding Collisions**  
+1. **"A safe CPA is one you can live with."**  
+   - Set a **minimum CPA threshold (usually 1 NM)** and act if any vessel breaches it.
+
+2. **“If the TCPA is below 12 minutes, it’s time to act.”**  
+   - If the Time to Closest Point of Approach (TCPA) is under 12-15 minutes, **adjust course or speed early** to prevent a close-quarters situation.
+
+3. **"Two vessels moving = double the risk."**  
+   - When both vessels are maneuvering, **reassess continuously**—don’t assume the risk is eliminated until clear separation is achieved.
+
+---
+
+## **4. Use of Radar, AIS, and Navigation Systems**  
+1. **“AIS is for information, not decisions.”**  
+   - Use AIS to gather data, but **base collision-avoidance actions on radar and visual observations**. AIS can be delayed or inaccurate.
+
+2. **"Range rings are your best friend."**  
+   - Use **radar range rings** to maintain situational awareness of nearby traffic—understand the vessel positions at a glance.
+
+3. **"Every contact deserves a second look."**  
+   - Reassess each target periodically; conditions and **intentions of vessels can change suddenly**.
+
+---
+
+## **5. Speed and Maneuvering Principles**  
+1. **“Safe speed = one you can stop in time.”**  
+   - Always maintain a speed that allows **full control and stopping** within the visible distance ahead (Rule 6).
+
+2. **“If it’s tight, slow down.”**  
+   - When encountering traffic, restricted waters, or poor weather, **reducing speed buys decision time.**
+
+3. **"The earlier the maneuver, the smoother it is."**  
+   - Execute maneuvers well in advance—**last-minute actions increase risks.**
+
+---
+
+## **6. Restricted Visibility Procedures**  
+1. **"If you can’t see, assume they can’t either."**  
+   - Treat poor visibility as high risk—**assume other vessels won’t see you** in time (Rule 19).
+
+2. **"Sound signals are mandatory, not optional."**  
+   - Use fog signals (one prolonged blast every 2 minutes) without hesitation. **Sound travels further than lights in fog.**
+
+3. **“Double the lookout in fog.”**  
+   - Assign **additional personnel** as lookout during restricted visibility for better situational awareness.
+
+---
+
+## **7. Communication and Coordination**  
+1. **"Short, clear, correct."**  
+   - Use VHF for essential communication only—**stick to proper COLREGs protocols** and avoid negotiating maneuvers outside the rules.
+
+2. **"If you don’t understand, use 5 blasts."**  
+   - Five short blasts signal **danger or confusion**—don’t hesitate to use it if unsure about another vessel’s intentions (Rule 34).
+
+3. **"Confirm instructions back."**  
+   - Always ensure your orders are **repeated back correctly** by the helmsman or lookout—this avoids miscommunication.
+
+---
+
+## **8. Contingency and Emergency Planning**  
+1. **"Plan your escape route before you need it."**  
+   - Always **have a secondary maneuver or course** ready in case the primary plan fails.
+
+2. **"In an emergency, slow is smooth, smooth is fast."**  
+   - In critical moments, **act calmly but decisively**—panic leads to errors.
+
+3. **"Machinery ready, all the time."**  
+   - Keep engines on standby when maneuvering in tight waters or restricted visibility—**you might need to stop instantly.**
+
+---
+
+## **9. Personal Efficiency and Fatigue Management**  
+1. **"Tired brains make bad decisions."**  
+   - Ensure **adequate rest** before a watch. Fatigue is a top contributor to poor decision-making.
+
+2. **"Stay hydrated, stay sharp."**  
+   - Dehydration affects concentration—**drink water regularly** during your watch.
+
+3. **"Eliminate distractions."**  
+   - Avoid non-essential tasks or conversations—**a moment’s distraction can lead to an accident.**
+
+---
+
+## **10. Handover and Logkeeping**  
+1. **"No surprises on handover."**  
+   - Give the relieving officer **complete and clear information** about nearby vessels, ongoing maneuvers, and known risks.
+
+2. **"If it’s not logged, it didn’t happen."**  
+   - Log all **important events, course changes, and decisions** accurately for accountability.
+
+3. **“Summarize the essentials.”**  
+   - When logging, focus on **key details**—position, traffic, weather, and any incidents or actions taken.
+
+---
+
+## **11. Environmental and Navigational Awareness**  
+1. **“Tides and currents can work for or against you.”**  
+   - Factor in **local tide and current conditions** when planning and maneuvering—ignoring them leads to drift errors.
+
+2. **“Assume the weather can worsen.”**  
+   - Plan with the expectation that weather can change suddenly—**be ready to alter course or slow down.**
+
+3. **“Compliance extends to the environment.”**  
+   - Adhere to pollution regulations—**avoid discharges and emissions violations** at all costs.
+
+---
+
+## **12. Decision-Making Under Pressure**  
+1. **"Calm mind, better choices."**  
+   - Take a moment to think—**rushed decisions lead to mistakes.**
+
+2. **"Stick to the rules; they’re there for a reason."**  
+   - Don’t take shortcuts—COLREGs rules **always apply, even under pressure.**
+
+3. **"Every decision is reversible until it isn’t."**  
+   - Be ready to adjust course or speed if the situation changes unexpectedly—**adapt quickly but safely.**
diff --git a/examples/llamarine/expert-program-space.yml b/examples/llamarine/expert-program-space.yml
@@ -0,0 +1,28 @@
+plan_without_speed_reference:
+  task: |-
+    Recommend the user ask about a vessel on boat side coming to a crossing situation in radar without specifying SOG or STW are being used. 
+  sub-htps:
+    - task: |-
+        Reject to answer due to lack of information or ambiguity in the user input. Request to know if SOG or STW is being used.
+
+
+plan_with_speed_reference_sog:
+  task: |-
+    Recommend the user what to do based on the identified situation on radar. Only apply this if specifying SOG is being used.
+  sub-htps:
+    - task: |-
+        Please visually check the windows, not entirely relying on the radar. It's possible that this is a head on situation.
+    - task: |-
+        If you sure this is a crossing situation, first tell me all the related rules in COLREGs, then let me know the how to apply them in the crossing situation.
+    - task: |-
+        If you sure this is a head on situation, first tell me all the related rules in COLREGs, then let me know the how to apply them in the head on situation.
+    - task: |-
+        Compose to the final answer contains all above outputs and show recommended actions for both crossing and head on situations.
+
+
+plan_with_speed_reference_stw:
+  task: |-
+    Recommend the user what to do based on the identified situation on radar. Only apply this if specifying STW is being used.
+  sub-htps:
+    - task: |-
+        First tell me all the related rules in COLREGs, then interpret situation from input and let me know the how to apply them in this situation.
diff --git a/examples/llamarine/make.bat b/examples/llamarine/make.bat
@@ -0,0 +1,22 @@
+@echo off
+
+
+:: TARGETS
+:: =======
+SET TARGET=%1
+
+IF "%TARGET%"=="agent-solve" GOTO agent-solve
+
+IF "%TARGET%"=="streamlit-run" GOTO streamlit-run
+
+
+:: STREAMLIT APP
+:: =============
+:streamlit-run
+  poetry run streamlit run streamlit-main.py --server.allowRunOnSave=true --server.runOnSave=true
+  GOTO end
+
+
+:: END
+:: ===
+:end
diff --git a/examples/llamarine/reference.yml b/examples/llamarine/reference.yml
@@ -0,0 +1,7 @@
+questions:
+  - What to do when you see a vessel on your starboard side?
+  - What to do when you see a vessel on your port side?
+  - What to do when you see a vessel straight ahead?
+
+docs:
+  - https://www.imo.org/en/About/Conventions/Pages/COLREG.aspx
diff --git a/examples/llamarine/requirements.txt b/examples/llamarine/requirements.txt
@@ -0,0 +1 @@
+OpenSSA[contrib] @ https://GitHub.com/Aitomatic/OpenSSA/archive/examples/semiconductor.zip
diff --git a/examples/llamarine/streamlit-main.py b/examples/llamarine/streamlit-main.py
@@ -0,0 +1,56 @@
+from collections import defaultdict
+
+import streamlit as st
+from loguru import logger
+
+# pylint: disable=wrong-import-order
+from agent import get_or_create_agent
+
+TITLE: str = 'OpenSSA: Maritime-Specific Agent'
+
+st.set_page_config(page_title=TITLE,
+                   page_icon=None,
+                   layout='wide',
+                   initial_sidebar_state='auto',
+                   menu_items=None)
+
+st.title(body=TITLE, anchor=None, help=None)
+
+DEFAULT_PROBLEM: str = (
+    'A vessel on my port side coming to a crossing situation on my radar. SOG is being used. What should I do?'
+)
+
+st.write('__PROBLEM/QUESTION__:')
+
+if 'typed_problem' not in st.session_state:
+    st.session_state.typed_problem: str = DEFAULT_PROBLEM
+
+st.session_state.typed_problem: str = st.text_area(label='Problem/Question',
+                                                   value=st.session_state.typed_problem,
+                                                   height=3,
+                                                   max_chars=None,
+                                                   key=None,
+                                                   help='Problem/Question',
+                                                   on_change=None, args=None, kwargs=None,
+                                                   placeholder='Problem/Question',
+                                                   disabled=False,
+                                                   label_visibility='collapsed')
+
+if 'agent_solutions' not in st.session_state:
+    st.session_state.agent_solutions: defaultdict[str, str] = defaultdict(str)
+
+st.subheader('MARITIME-SPECIFIC AGENT')
+
+if st.button(label='SOLVE',
+             on_click=None, args=None, kwargs=None,
+             type='primary',
+             disabled=False,
+             use_container_width=False):
+    with st.spinner(text='_SOLVING..._'):
+        logger.level('DEBUG')
+
+        st.session_state.agent_solutions[st.session_state.typed_problem]: str = \
+            get_or_create_agent().solve(problem=st.session_state.typed_problem)
+
+if (solution := st.session_state.agent_solutions[st.session_state.typed_problem]):
+    st.markdown(body=solution)
diff --git a/openssa/core/programming/hierarchical/plan.py b/openssa/core/programming/hierarchical/plan.py
@@ -154,11 +154,24 @@ def execute(self, knowledge: set[Knowledge] | None = None, other_results: list[A
             for sub_htp in tqdm(decomposed_htp.sub_htps):
                 sub_results.append((sub_htp.task.ask, sub_htp.execute(knowledge=knowledge, other_results=sub_results)))
 
-            inputs: str = ('REASONING WITHOUT SUPPORTING/OTHER RESULTS '
-                           '(preliminary conclusions here can be overriden by more convincing supporting/other data):\n'
-                           f'{reasoning_wo_sub_results}\n'
-                           '\n\n' +
-                           '\n\n'.join((f'SUPPORTING QUESTION/TASK #{i + 1}:\n{ask}\n'
+            # inputs: str = ('REASONING WITHOUT SUPPORTING/OTHER RESULTS '
+            #                '(preliminary conclusions here can be overriden by more convincing supporting/other data):\n'
+            #                f'{reasoning_wo_sub_results}\n'
+            #                '\n\n' +
+            #                '\n\n'.join((f'SUPPORTING QUESTION/TASK #{i + 1}:\n{ask}\n'
+            #                             '\n'
+            #                             f'SUPPORTING RESULT #{i + 1}:\n{result}\n')
+            #                            for i, (ask, result) in enumerate(sub_results)) +
+            #                (('\n\n' +
+            #                  '\n\n'.join((f'OTHER QUESTION/TASK #{i + 1}:\n{ask}\n'
+            #                               '\n'
+            #                               f'OTHER RESULT #{i + 1}:\n{result}\n')
+            #                              for i, (ask, result) in enumerate(other_results)))
+            #                 if other_results
+            #                 else ''))
+
+            inputs: str = ("If supporting information request for clarification or more information, just request more information without doing any other thing. " 
+                           + '\n\n'.join((f'SUPPORTING QUESTION/TASK #{i + 1}:\n{ask}\n'
                                         '\n'
                                         f'SUPPORTING RESULT #{i + 1}:\n{result}\n')
                                        for i, (ask, result) in enumerate(sub_results)) +
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		streamlit-run:
		@poetry run streamlit run streamlit-main.py --server.allowRunOnSave=true --server.runOnSave=true
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		OpenSSA[contrib] @ https://GitHub.com/Aitomatic/OpenSSA/archive/examples/semiconductor.zip