Merge pull request #378 from aitomatic/examples/semicon-optim

Examples: semicon optim + llamarine

.gitignore

@@ -39,6 +39,13 @@ docs/_build/
 # DATA & EXAMPLE FILES
 # ====================
 examples/**/*.json
+!examples/**/package.json
+!examples/**/package-lock.json
+
+
+# Exception
+!examples/semiconductor/semiconductor-ui/api/poetry.lock
+
 .openssa/
 test*.ipynb
 tmp/

examples/llamarine/.env.template

@@ -0,0 +1 @@
+OPENAI_API_KEY=

examples/llamarine/Makefile

@@ -0,0 +1,2 @@
+streamlit-run:
+	@poetry run streamlit run streamlit-main.py --server.allowRunOnSave=true --server.runOnSave=true

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`

examples/llamarine/agent.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+from functools import cache
+
+from data_and_knowledge import EXPERT_PROGRAMS, EXPERT_KNOWLEDGE
+from openssa import DANA, ProgramStore, HTP, HTPlanner, OpenAILM
+
+
+@cache
+def get_or_create_agent(max_depth=2, max_subtasks_per_decomp=4) -> DANA:
+    lm = OpenAILM.from_defaults()
+
+    program_store = ProgramStore(lm=lm)
+    if EXPERT_PROGRAMS:
+        for program_name, htp_dict in EXPERT_PROGRAMS.items():
+            htp = HTP.from_dict(htp_dict)
+            program_store.add_or_update_program(name=program_name, description=htp.task.ask, program=htp)
+
+    return DANA(program_store=program_store,
+                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))

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_PATH: Path = Path(__file__).parent / 'expert-knowledge.txt'
+with open(file=EXPERT_KNOWLEDGE_PATH,
+          buffering=-1,
+          encoding='utf-8',
+          errors='strict',
+          newline=None,
+          closefd=True,
+          opener=None) as f:
+    EXPERT_KNOWLEDGE: str = f.read()
+
+
+EXPERT_PROGRAMS_PATH: Path = Path(__file__).parent / 'expert-programs.yml'
+with open(file=EXPERT_PROGRAMS_PATH,
+          buffering=-1,
+          encoding='utf-8',
+          errors='strict',
+          newline=None,
+          closefd=True,
+          opener=None) as f:
+    EXPERT_PROGRAMS: dict[str, HTPDict] = yaml.safe_load(stream=f)

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.**

examples/llamarine/expert-programs.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.

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

examples/llamarine/reference.yml

@@ -0,0 +1,7 @@
+questions:
+  - A vessel on my port side coming to a crossing situation on my radar. What should I do?
+  - A vessel on my port side coming to a crossing situation on my radar. STW is being used. What should I do?
+  - A vessel on my port side coming to a crossing situation on my radar. SOG is being used. What should I do?
+
+docs:
+  - https://www.imo.org/en/About/Conventions/Pages/COLREG.aspx

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, allow_reject=True)
+
+if (solution := st.session_state.agent_solutions[st.session_state.typed_problem]):
+    st.markdown(body=solution)

examples/semiconductor/agent.py

@@ -3,10 +3,9 @@
 from argparse import ArgumentParser
 from functools import cache
 
-from openssa import DANA, ProgramStore, HTP, HTPlanner, OpenAILM
-
 # pylint: disable=wrong-import-order
-from data_and_knowledge import EXPERT_PROGRAMS
+from data_and_knowledge import EXPERT_PROGRAMS, EXPERT_KNOWLEDGE
+from openssa import DANA, ProgramStore, HTP, HTPlanner, OpenAILM
 from semikong_lm import SemiKongLM
 
 
@@ -20,9 +19,9 @@ def get_or_create_agent(use_semikong_lm: bool = True, max_depth=2, max_subtasks_
             htp = HTP.from_dict(htp_dict)
             program_store.add_or_update_program(name=program_name, description=htp.task.ask, program=htp)
 
-    return DANA(knowledge={},
-                program_store=program_store,
+    return DANA(program_store=program_store,
                 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={})