study-mate-agent 0.1.2__py3-none-any.whl

study_mate_agent/agents/tutor.py

@@ -0,0 +1,249 @@
+import uuid as _0x_uuid
+import datetime as _0x_datetime
+from typing import AsyncGenerator as _0x_AG, Optional as _0x_Opt
+
+from agents import (
+    Agent as _0x_A,
+    function_tool as _0x_ft,
+    Runner as _0x_R,
+    trace as _0x_tr,
+    ModelSettings as _0x_MS,
+    RunResultStreaming as _0x_RRS,
+    RawResponsesStreamEvent as _0x_RRSE,
+)
+from openai.types.responses import (
+    EasyInputMessageParam as _0x_EIMP,
+    ResponseTextDeltaEvent as _0x_RTDE,
+    ResponseContentPartDoneEvent as _0x_RCPDE,
+    ResponseOutputText as _0x_ROT,
+    ResponseCreatedEvent as _0x_RCE,
+    Response as _0x_Resp,
+)
+
+from study_mate_agent._codec import _0xdec as _0x_d
+from study_mate_agent.ports.tutor import TeachingTutorAgent
+from study_mate_agent.ports.embedder import EmbedderClient
+from study_mate_agent.models.message import Message
+from study_mate_agent.models.chunk import EmbedChunkModel
+from study_mate_agent.models.llm import LLMClientModel
+from study_mate_agent.models.material import SearchMaterialModel
+from study_mate_agent.models.stream import (
+    StreamCompletedEventModel,
+    StreamCreatedEventModel,
+    StreamDeltaEventModel,
+)
+from study_mate_agent.mappers.message_mapper import to_llm_messages as _0x_tlm
+from study_mate_agent.prompts.tutor_prompt import get_tutor_system_prompt as _0x_gtsp
+
+_0x_TTD = "\u0065\u004a\u0078\u0074\u006b\u0073\u0031\u0071\u0032\u0030\u0041\u0051\u0078\u002b\u0039\u0036\u0069\u0073\u0047\u006e\u0042\u004e\u0049\u002b\u0051\u0046\u002b\u006d\u0045\u0050\u0043\u0070\u0074\u0049\u0064\u0043\u0036\u0061\u0045\u0055\u0035\u0047\u0068\u004e\u005a\u0064\u006b\u006b\u0067\u006d\u0059\u0064\u0075\u0055\u0069\u004f\u0051\u006d\u0053\u0055\u0047\u0045\u0046\u0055\u0057\u0034\u006c\u0056\u006f\u006c\u004d\u0065\u005a\u0032\u0066\u0032\u0048\u0054\u0070\u006a\u0032\u0059\u006b\u0043\u004f\u0063\u0031\u0071\u0050\u006e\u002f\u007a\u0048\u0031\u0046\u0053\u0041\u0056\u0030\u0033\u0056\u004e\u0035\u0051\u0045\u006f\u0048\u0056\u004d\u0077\u0072\u0075\u0067\u0065\u0059\u0068\u0058\u006b\u0039\u0077\u0030\u0059\u0042\u005a\u0075\u0065\u0053\u004e\u0072\u0049\u0035\u0078\u006e\u004c\u0031\u0033\u006e\u0050\u0059\u0054\u0063\u004d\u004a\u006d\u0041\u0041\u0063\u002f\u0076\u0076\u0066\u0037\u006e\u007a\u0035\u002b\u002b\u0066\u0062\u0035\u0075\u0050\u002f\u0031\u005a\u0039\u0074\u006c\u0058\u0035\u0074\u0050\u0044\u006a\u0038\u0034\u0037\u0038\u0043\u0055\u0057\u0076\u0070\u0053\u004e\u004a\u0041\u0043\u0069\u0065\u0055\u006a\u004f\u004c\u0043\u0065\u0053\u0033\u004e\u0046\u0051\u0057\u0061\u0039\u0077\u0070\u0034\u0072\u0073\u0047\u0065\u0046\u0031\u0054\u0065\u0048\u006e\u0066\u0079\u0067\u0077\u004b\u0053\u0068\u0070\u004d\u004c\u0066\u0038\u0064\u004f\u006d\u0064\u0065\u004b\u0077\u0074\u006b\u0048\u004e\u0078\u0061\u0063\u0052\u0042\u0079\u0068\u0033\u0041\u0056\u0065\u002b\u006a\u0065\u0072\u006e\u0036\u0068\u0030\u0064\u0068\u0070\u0045\u0045\u0053\u0051\u0063\u0059\u006e\u0050\u004d\u0043\u006e\u006e\u0041\u0077\u0050\u0069\u0037\u0071\u007a\u0071\u0059\u0074\u004a\u006b\u0064\u006f\u0048\u004e\u0075\u004c\u0043\u004c\u0043\u006f\u004b\u0059\u0032\u0050\u0077\u004b\u0077\u0062\u0074\u006b\u0043\u0070\u0078\u0076\u0048\u0039\u0045\u0064\u0042\u0066\u0052\u0057\u006b\u0049\u0070\u0069\u0034\u0070\u0063\u0034\u0056\u0076\u0033\u0065\u0044\u0079\u0046\u006f\u006a\u0068\u0055\u0069\u0031\u0038\u004a\u0079\u007a\u0061\u0032\u0063\u0069\u0055\u004c\u0070\u0068\u004e\u007a\u0044\u0037\u0048\u0045\u0065\u0039\u006c\u0042\u0061\u0067\u006e\u0077\u0048\u0054\u0030\u0045\u004c\u0066\u0071\u0043\u0059\u0058\u0049\u0036\u0079\u0055\u006b\u006b\u0072\u002b\u0053\u0033\u005a\u0051\u0078\u0044\u0073\u004f\u006e\u0044\u0066\u0032\u0035\u0070\u0057\u006e\u0046\u004e\u0076\u0049\u005a\u0067\u0069\u0035\u0043\u0055\u0064\u0070\u0071\u0062\u006c\u0059\u0038\u006d\u006e\u0058\u004b\u004f\u0046\u0070\u0052\u0050\u0075\u006a\u0063\u0078\u0038\u0034\u0030\u0072\u0069\u0075\u0072\u0074\u0079\u0076\u006a\u0038\u0074\u0046\u004f\u0066\u0055\u0071\u0055\u0044\u0048\u0038\u0031\u0072\u0072\u0063\u0037\u0041\u0043\u0035\u002f\u0041\u0054\u0034\u006f\u0075\u0073\u0074\u0036\u0037\u004f\u0075\u0049\u0076\u0049\u0033\u0051\u0066\u004e\u0045\u0044\u0057\u006b\u0056\u0034\u0032\u0051\u0044\u0046\u0069\u0076\u0035\u0046\u004d\u006f\u004b\u006d\u0074\u0061\u006c\u0048\u006e\u0063\u005a\u0076\u0062\u0064\u0069\u0052\u0066\u004c\u0065\u0072\u004a\u004e\u0033\u0056\u007a\u0034\u0044\u0078\u0048\u0076\u0071\u004b\u0058\u0079\u0072\u0044\u0035\u0064\u0044\u0071\u0046\u004d\u0069\u0058\u0053\u0033\u0053\u0051\u0035\u0062\u004b\u0070\u0059\u0070\u0057\u0042\u0054\u0067\u006f\u0061\u005a\u0077\u004a\u0074\u0079\u0068\u006b\u006c\u0037\u0075\u0035\u0058\u005a\u0048\u0031\u0059\u002f\u004a\u0066\u0073\u0076\u0059\u006f\u007a\u0058\u0072\u002b\u006f\u0054\u004f\u0056\u0075\u0052\u002b\u0057\u002b\u0033\u004c\u0050\u004e\u002b\u0077\u0039\u0053\u0063\u0073\u004f\u0059"
+_0x_TER = "\u0065\u004a\u0078\u0046\u006a\u0074\u0031\u0071\u0077\u006b\u0041\u0051\u0068\u0065\u0039\u0039\u0069\u006e\u006d\u0041\u0034\u0069\u0073\u0056\u0043\u0072\u006b\u0071\u004c\u0056\u0053\u0051\u0055\u006b\u0054\u0059\u0036\u006c\u0071\u0032\u0070\u0071\u0057\u0042\u005a\u006a\u0056\u004b\u0046\u0043\u0057\u004b\u0073\u0056\u0065\u0069\u0032\u007a\u0059\u0058\u0065\u0061\u004c\u004d\u0032\u0058\u0066\u006f\u004a\u0049\u0069\u0039\u0047\u0038\u0036\u0063\u006e\u0036\u002f\u0033\u0030\u0041\u0030\u0036\u0054\u0033\u0033\u0069\u0064\u0055\u0071\u0039\u0078\u0079\u0043\u0034\u0076\u0062\u0037\u0076\u0033\u0074\u0030\u0045\u006e\u0054\u0036\u0079\u0045\u006f\u0065\u0063\u0073\u0049\u0077\u0034\u0065\u002b\u004e\u0074\u0053\u0064\u0056\u0052\u0059\u0066\u006a\u0071\u004a\u0077\u005a\u0070\u0079\u0059\u004f\u0045\u004b\u0071\u0064\u0034\u006c\u0052\u004d\u0050\u0048\u004f\u005a\u0037\u004c\u0042\u0078\u0068\u002b\u006f\u004c\u0078\u004e\u0034\u0065\u0047\u0077\u0030\u0032\u0037\u0068\u0065\u0045\u007a\u0055\u006b\u0033\u0056\u0049\u0065\u0056\u0052\u0056\u0045\u0064\u006b\u0067\u0050\u0057\u006e\u0054\u0078\u0052\u0035\u004b\u002b\u0066\u0052\u0045\u004c\u002f\u0048\u0068\u0044\u0044\u006c\u0044\u002b\u0032\u0074\u0049\u007a\u0034\u0035\u0036\u0041\u004c\u007a\u0075\u0045\u0033\u0056\u0062\u0038\u0048\u004c\u0052\u0050\u0053\u0036\u0055\u0039\u0070\u0034\u0037\u0031\u0072\u004e\u0051\u0073\u004f\u0045\u0061\u0051\u0051\u0074\u0044\u0061\u004a\u006e\u004f\u0058\u0061\u004b\u0059\u004d\u0064\u0059\u0071\u0041\u0074\u004a\u0053\u0054\u0043\u004a\u0067\u004a\u0074\u002f\u006d\u0073\u0061\u0038\u004c\u0063\u0034\u0046\u0046\u0032\u0064\u0052\u0070\u002f\u0033\u004d\u0079\u0075\u0056\u0074\u0055\u0070\u0031\u0057\u0056\u0034\u0053\u0066\u0047\u004d\u0056\u0061\u0065\u004f\u006f\u004a\u0036\u0041\u0031\u002f\u006a\u0065\u0052\u0056\u002b\u0033\u0068\u006e\u007a\u006e\u0078\u002f\u0073\u006f\u0076\u0041\u0034\u0067\u003d\u003d"
+_0x_TFR = "\u0065\u004a\u0077\u0056\u006a\u0055\u0045\u004b\u0077\u006a\u0041\u0055\u0052\u0050\u0063\u0039\u0078\u0054\u002b\u0042\u0042\u002f\u0041\u0079\u0067\u0070\u004b\u0046\u0053\u0043\u0076\u0057\u0046\u0070\u0045\u0051\u004b\u0044\u0052\u0043\u0068\u0053\u0077\u0055\u0044\u0046\u0052\u0070\u0052\u0061\u006d\u0043\u0075\u006f\u0071\u0031\u0059\u0049\u0058\u0069\u0067\u005a\u004b\u0066\u004f\u0078\u0067\u0058\u0077\u0079\u007a\u0065\u0038\u0049\u0062\u004f\u0059\u0068\u0049\u0075\u0047\u0064\u0041\u0046\u0049\u005a\u004e\u0042\u0045\u0050\u0074\u0044\u0045\u006a\u004b\u0073\u004f\u006c\u0051\u0033\u0077\u004f\u0050\u0047\u0056\u0041\u004a\u0030\u006e\u0057\u0043\u0036\u0064\u0071\u0058\u0030\u0071\u0077\u004d\u0036\u006d\u0073\u005a\u0042\u0078\u0050\u0053\u007a\u0036\u0058\u0074\u0030\u0048\u0042\u0046\u002f\u007a\u006a\u007a\u006b\u0046\u002f\u004e\u0059\u0057\u0058\u006b\u0043\u0049\u0077\u0056\u0067\u0077\u0066\u002f\u0042\u0054\u0077\u0035\u0032\u0057\u002b\u0068\u0057\u006d\u0057\u0073\u0048\u002b\u0074\u0030\u0061\u006b\u005a\u0068\u007a\u0041\u0056\u0069\u0032\u0065\u004c\u0068\u0062\u0032\u0059\u0043\u0056\u0065\u0030\u0078\u004c\u004c\u0042\u0074\u0041\u0039\u0055\u0058\u004a\u006a\u0064\u004e\u006a\u006c\u0072\u0076\u0066\u0054\u004e\u0066\u0043\u0034\u0052\u0079\u0035\u0032\u002b\u0035\u0036\u0050\u0077\u0071\u0058\u0059\u0059\u004d\u003d"
+_0x_NO_EMB = "eJyqVrVSqlKjSUvUs7hKkfLLEjcUkexIR2WpVFKnu7iFiQGqJmvivfJ3elkRpF9VisceAhjrLzeTvdtTe2mvbDq2TRXtftP7W4oAK5eBgA=="
+
+
+class TeachingTutorOpenAIAgent(TeachingTutorAgent):
+
+    def __init__(
+        self,
+        agent_model: str = "gpt-6-luna",
+        embedder_client: _0x_Opt[EmbedderClient] = None,
+        max_searches: int = 5,
+        temperature: float = 0.0,
+        tool_choice: str = "required",
+        system_prompt_template: _0x_Opt[str] = None,
+        additional_rules: _0x_Opt[str] = None,
+    ):
+        self.agent_model = agent_model
+        self.embedder_client = embedder_client
+        self.max_searches = max_searches
+        self.temperature = temperature
+        self.tool_choice = tool_choice
+        self.system_prompt_template = system_prompt_template
+        self.additional_rules = additional_rules
+
+    async def _search_course_materials(
+        self,
+        bucket_id: _0x_uuid.UUID,
+        query: str,
+        week_number: int,
+    ) -> tuple[str, list[EmbedChunkModel]]:
+        if not self.embedder_client:
+            return _0x_d(_0x_NO_EMB), []
+
+        _0x_res: list[EmbedChunkModel] = await self.embedder_client.embed_hybrid_query(
+            bucket_id,
+            query,
+        )
+
+        if len(_0x_res) == 0:
+            _0x_mat = _0x_d(_0x_TER).format(
+                query=query,
+                week_number=week_number,
+            )
+        else:
+            _0x_lines = chr(10).join([f'{r.source_name} |{r.timeline}|{r.text}' for r in _0x_res])
+            _0x_mat = _0x_d(_0x_TFR).format(
+                query=query,
+                week_number=week_number,
+                count=len(_0x_res),
+                items=_0x_lines,
+            )
+
+        return _0x_mat, _0x_res
+
+    async def _create_agent(
+        self,
+        bucket_id: _0x_uuid.UUID,
+        week_number: int,
+        course_name: str,
+        week_topic: str,
+        embed_chunk_models: list[EmbedChunkModel],
+        max_searches: _0x_Opt[int] = None,
+        additional_rules: _0x_Opt[str] = None,
+        system_prompt_template: _0x_Opt[str] = None,
+    ) -> _0x_A:
+        _0x_ms = max_searches if max_searches is not None else self.max_searches
+        _0x_ar = additional_rules if additional_rules is not None else self.additional_rules
+        _0x_tmpl = system_prompt_template if system_prompt_template is not None else self.system_prompt_template
+
+        @_0x_ft(
+            name_override="search_course_materials",
+            description_override=_0x_d(_0x_TTD).format(week_number=week_number),
+        )
+        async def search_course_materials(
+            query: str,
+        ) -> str:
+            _0x_mat, _0x_res = await self._search_course_materials(
+                bucket_id=bucket_id,
+                query=query,
+                week_number=week_number,
+            )
+
+            embed_chunk_models.clear()
+            embed_chunk_models.extend(_0x_res)
+
+            return _0x_mat
+
+        return _0x_A(
+            name="teaching tutor",
+            instructions=_0x_gtsp(
+                course_name=course_name,
+                week_number=week_number,
+                week_topic=week_topic,
+                max_searches=_0x_ms,
+                template=_0x_tmpl,
+                additional_rules=_0x_ar,
+            ),
+            model_settings=_0x_MS(
+                tool_choice=self.tool_choice,
+            ),
+            model=self.agent_model,
+            output_type=str,
+            tools=[search_course_materials],
+        )
+
+    async def create(
+        self,
+        bucket_id: _0x_uuid.UUID,
+        messages: list[Message],
+        course_name: str,
+        week_number: int,
+        week_topic: str,
+        max_turns: int = 5,
+        max_searches: _0x_Opt[int] = None,
+        additional_rules: _0x_Opt[str] = None,
+        system_prompt_template: _0x_Opt[str] = None,
+    ) -> SearchMaterialModel:
+        _0x_ecm: list[EmbedChunkModel] = []
+
+        _0x_ag = await self._create_agent(
+            bucket_id=bucket_id,
+            week_number=week_number,
+            course_name=course_name,
+            week_topic=week_topic,
+            embed_chunk_models=_0x_ecm,
+            max_searches=max_searches,
+            additional_rules=additional_rules,
+            system_prompt_template=system_prompt_template,
+        )
+
+        _0x_im: list[_0x_EIMP] = []
+        _0x_im.extend(_0x_tlm(messages))
+
+        with _0x_tr("teaching tutor"):
+            _0x_run = await _0x_R.run(_0x_ag, _0x_im, max_turns=max_turns)
+            _0x_out = _0x_run.final_output
+
+        _0x_llm = LLMClientModel(
+            text=_0x_out,
+            temperature=self.temperature,
+            model=self.agent_model,
+            input_tokens=0,
+            output_tokens=0,
+        )
+
+        return SearchMaterialModel(_0x_llm, _0x_ecm)
+
+    async def create_stream(
+        self,
+        bucket_id: _0x_uuid.UUID,
+        messages: list[Message],
+        course_name: str,
+        week_number: int,
+        week_topic: str,
+        max_turns: int = 5,
+        max_searches: _0x_Opt[int] = None,
+        additional_rules: _0x_Opt[str] = None,
+        system_prompt_template: _0x_Opt[str] = None,
+    ) -> _0x_AG[
+        StreamCompletedEventModel | StreamCreatedEventModel | StreamDeltaEventModel,
+        None,
+    ]:
+        _0x_ecm: list[EmbedChunkModel] = []
+
+        _0x_ag = await self._create_agent(
+            bucket_id=bucket_id,
+            week_number=week_number,
+            course_name=course_name,
+            week_topic=week_topic,
+            embed_chunk_models=_0x_ecm,
+            max_searches=max_searches,
+            additional_rules=additional_rules,
+            system_prompt_template=system_prompt_template,
+        )
+
+        _0x_im: list[_0x_EIMP] = []
+        _0x_im.extend(_0x_tlm(messages))
+
+        with _0x_tr("teaching tutor stream"):
+            _0x_rrs: _0x_RRS = _0x_R.run_streamed(_0x_ag, _0x_im, max_turns=max_turns)
+            _0x_ces = False
+
+            async for _0x_ev in _0x_rrs.stream_events():
+                if isinstance(_0x_ev, _0x_RRSE) and isinstance(_0x_ev.data, _0x_RTDE):
+                    yield StreamDeltaEventModel(content=_0x_ev.data.delta)
+
+                elif (
+                    isinstance(_0x_ev, _0x_RRSE)
+                    and isinstance(_0x_ev.data, _0x_RCPDE)
+                    and isinstance(_0x_ev.data.part, _0x_ROT)
+                ):
+                    yield StreamCompletedEventModel(
+                        content=_0x_ev.data.part.text,
+                        intput_tokens=0,
+                        output_tokens=0,
+                        sources=_0x_ecm,
+                    )
+
+                elif (
+                    isinstance(_0x_ev, _0x_RRSE)
+                    and isinstance(_0x_ev.data, _0x_RCE)
+                    and isinstance(_0x_ev.data.response, _0x_Resp)
+                ):
+                    if not _0x_ces:
+                        _0x_ces = True
+                        yield StreamCreatedEventModel(
+                            created_at=int(_0x_datetime.datetime.now().timestamp()),
+                            temperature=self.temperature,
+                            model=_0x_ev.data.response.model,
+                        )

study_mate_agent/mappers/__init__.py

@@ -0,0 +1,4 @@
+from study_mate_agent.mappers.message_mapper import to_llm_messages
+
+__all__ = ["to_llm_messages"]
+

study_mate_agent/mappers/message_mapper.py

@@ -0,0 +1,15 @@
+from openai.types.responses import EasyInputMessageParam
+from study_mate_agent.models.message import Message
+
+
+def to_llm_messages(messages: list[Message]) -> list[EasyInputMessageParam]:
+    llm_messages: list[EasyInputMessageParam] = []
+
+    for message in messages:
+        llm_messages.append({
+            "role": message.role.label,
+            "content": message.content,
+        })
+
+    return llm_messages
+

study_mate_agent/models/__init__.py

@@ -0,0 +1,24 @@
+from study_mate_agent.models.chunk import EmbedChunkModel
+from study_mate_agent.models.llm import LLMClientModel
+from study_mate_agent.models.material import SearchMaterialModel
+from study_mate_agent.models.message import Message, MessageRole, MessageRoleLabel
+from study_mate_agent.models.stream import (
+    StreamCreatedEventModel,
+    StreamDeltaEventModel,
+    StreamCompletedEventModel,
+    StreamRagEventModel,
+)
+
+__all__ = [
+    "EmbedChunkModel",
+    "LLMClientModel",
+    "SearchMaterialModel",
+    "Message",
+    "MessageRole",
+    "MessageRoleLabel",
+    "StreamCreatedEventModel",
+    "StreamDeltaEventModel",
+    "StreamCompletedEventModel",
+    "StreamRagEventModel",
+]
+

study_mate_agent/models/chunk.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class EmbedChunkModel:
+    text: str
+    source_id: int
+    similarity: float
+    timeline: Optional[str] = None
+    source_name: Optional[str] = None
+

study_mate_agent/models/llm.py

@@ -0,0 +1,29 @@
+class LLMClientModel:
+    text: str
+    temperature: float
+    model: str
+    input_tokens: int
+    output_tokens: int
+
+    def __init__(
+        self,
+        text: str,
+        temperature: float,
+        model: str,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+    ):
+        self.text = text
+        self.temperature = temperature
+        self.model = model
+        self.input_tokens = input_tokens
+        self.output_tokens = output_tokens
+
+    def __repr__(self) -> str:
+        return (
+            f"LLMClientModel(model={self.model!r}, "
+            f"temperature={self.temperature}, "
+            f"input_tokens={self.input_tokens}, "
+            f"output_tokens={self.output_tokens})"
+        )
+

study_mate_agent/models/material.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+from study_mate_agent.models.chunk import EmbedChunkModel
+from study_mate_agent.models.llm import LLMClientModel
+
+
+@dataclass
+class SearchMaterialModel:
+    llm_client_model: LLMClientModel
+    embed_chunk_models: list[EmbedChunkModel]
+

study_mate_agent/models/message.py

@@ -0,0 +1,61 @@
+import uuid
+from datetime import datetime
+from enum import StrEnum
+from typing import Literal, Optional, Any, cast
+
+MessageRoleLabel = Literal["system", "user", "assistant"]
+
+
+class MessageRole(StrEnum):
+    system = "system"
+    user = "user"
+    assistant = "assistant"
+
+    @property
+    def label(self) -> MessageRoleLabel:
+        return cast(MessageRoleLabel, self.value)
+
+    @classmethod
+    def from_label(cls, label: MessageRoleLabel | str) -> "MessageRole":
+        return cls(str(label))
+
+
+class Message:
+    id_: Optional[int]
+    content: str
+    thread_id: Optional[uuid.UUID]
+    role: MessageRole
+    message_bucket: Optional[Any]
+    usage: Optional[Any]
+    reaction: Optional[Any]
+    created_at: datetime
+
+    def __init__(
+        self,
+        content: str,
+        role: MessageRole | str = MessageRole.user,
+        id_: Optional[int] = None,
+        thread_id: Optional[uuid.UUID] = None,
+        message_bucket: Optional[Any] = None,
+        usage: Optional[Any] = None,
+        reaction: Optional[Any] = None,
+        created_at: Optional[datetime] = None,
+    ):
+        self.id_ = id_
+        self.content = content
+        self.thread_id = thread_id
+        self.role = role if isinstance(role, MessageRole) else MessageRole.from_label(role)
+        self.message_bucket = message_bucket
+        self.usage = usage
+        self.reaction = reaction
+        self.created_at = created_at or datetime.now()
+
+    def __eq__(self, other: Any) -> bool:
+        return isinstance(other, Message) and other.id_ == self.id_ and self.id_ is not None
+
+    def __hash__(self) -> int:
+        return hash(self.id_) if self.id_ is not None else hash((self.content, self.role))
+
+    def __repr__(self) -> str:
+        return f"Message(id_={self.id_}, content={self.content!r}, thread_id={self.thread_id}, role={self.role})"
+

study_mate_agent/models/stream.py

@@ -0,0 +1,38 @@
+from dataclasses import dataclass, field
+from typing import Optional
+from study_mate_agent.models.chunk import EmbedChunkModel
+
+
+@dataclass
+class StreamCreatedEventModel:
+    created_at: int
+    model: str
+    temperature: float
+
+
+@dataclass
+class StreamDeltaEventModel:
+    content: str
+
+
+@dataclass
+class StreamCompletedEventModel:
+    content: str
+    intput_tokens: int = 0
+    output_tokens: int = 0
+    sources: Optional[list[EmbedChunkModel]] = field(default_factory=list)
+    id: Optional[int] = None
+
+    @property
+    def input_tokens(self) -> int:
+        return self.intput_tokens
+
+    @input_tokens.setter
+    def input_tokens(self, value: int) -> None:
+        self.intput_tokens = value
+
+
+@dataclass
+class StreamRagEventModel:
+    sources: Optional[list[EmbedChunkModel]] = None
+

study_mate_agent/ports/__init__.py

@@ -0,0 +1,12 @@
+from study_mate_agent.ports.assistant import LectureAssistantAgent
+from study_mate_agent.ports.embedder import EmbedderClient
+from study_mate_agent.ports.study_week import StudyWeekAgent
+from study_mate_agent.ports.tutor import TeachingTutorAgent
+
+__all__ = [
+    "LectureAssistantAgent",
+    "EmbedderClient",
+    "StudyWeekAgent",
+    "TeachingTutorAgent",
+]
+

study_mate_agent/ports/assistant.py

@@ -0,0 +1,39 @@
+import uuid
+from abc import ABC, abstractmethod
+from typing import AsyncGenerator, Optional
+from study_mate_agent.models.message import Message
+from study_mate_agent.models.material import SearchMaterialModel
+from study_mate_agent.models.stream import (
+    StreamCompletedEventModel,
+    StreamCreatedEventModel,
+    StreamDeltaEventModel,
+)
+
+
+class LectureAssistantAgent(ABC):
+
+    @abstractmethod
+    async def create(
+        self,
+        bucket_id: uuid.UUID,
+        messages: list[Message],
+        week_number: int,
+        course_name: str,
+        max_turns: int = 5,
+        additional_rules: Optional[str] = None,
+        reference_date: Optional[str] = None,
+    ) -> SearchMaterialModel:
+        ...
+
+    @abstractmethod
+    async def create_stream(
+        self,
+        bucket_id: uuid.UUID,
+        messages: list[Message],
+        week_number: int,
+        course_name: str,
+        max_turns: int = 5,
+        additional_rules: Optional[str] = None,
+        reference_date: Optional[str] = None,
+    ) -> AsyncGenerator[StreamCompletedEventModel | StreamCreatedEventModel | StreamDeltaEventModel, None]:
+        ...

study_mate_agent/ports/embedder.py

@@ -0,0 +1,15 @@
+import uuid
+from abc import ABC, abstractmethod
+from study_mate_agent.models.chunk import EmbedChunkModel
+
+
+class EmbedderClient(ABC):
+
+    @abstractmethod
+    async def embed_query(self, bucket_id: uuid.UUID, query: str) -> list[EmbedChunkModel]:
+        ...
+
+    @abstractmethod
+    async def embed_hybrid_query(self, bucket_id: uuid.UUID, query: str) -> list[EmbedChunkModel]:
+        ...
+

study_mate_agent/ports/study_week.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class StudyWeekAgent(ABC):
+
+    @abstractmethod
+    async def find_study_week(
+        self,
+        query: str,
+        reference_date: Optional[str] = None,
+    ) -> Optional[int]:
+        ...

study_mate_agent/ports/tutor.py

@@ -0,0 +1,41 @@
+import uuid
+from abc import ABC, abstractmethod
+from typing import AsyncGenerator, Optional
+from study_mate_agent.models.message import Message
+from study_mate_agent.models.material import SearchMaterialModel
+from study_mate_agent.models.stream import (
+    StreamCompletedEventModel,
+    StreamCreatedEventModel,
+    StreamDeltaEventModel,
+)
+
+
+class TeachingTutorAgent(ABC):
+
+    @abstractmethod
+    async def create(
+        self,
+        bucket_id: uuid.UUID,
+        messages: list[Message],
+        course_name: str,
+        week_number: int,
+        week_topic: str,
+        max_turns: int = 5,
+        max_searches: Optional[int] = None,
+        additional_rules: Optional[str] = None,
+    ) -> SearchMaterialModel:
+        ...
+
+    @abstractmethod
+    async def create_stream(
+        self,
+        bucket_id: uuid.UUID,
+        messages: list[Message],
+        course_name: str,
+        week_number: int,
+        week_topic: str,
+        max_turns: int = 5,
+        max_searches: Optional[int] = None,
+        additional_rules: Optional[str] = None,
+    ) -> AsyncGenerator[StreamCompletedEventModel | StreamCreatedEventModel | StreamDeltaEventModel, None]:
+        ...

study_mate_agent/prompts/__init__.py

@@ -0,0 +1,8 @@
+from study_mate_agent.prompts.assistant_prompt import get_assistant_system_prompt
+from study_mate_agent.prompts.tutor_prompt import get_tutor_system_prompt
+
+__all__ = [
+    "get_assistant_system_prompt",
+    "get_tutor_system_prompt",
+]
+