ommlds 0.0.0.dev448__py3-none-any.whl → 0.0.0.dev450__py3-none-any.whl

ommlds/minichain/lib/todo/tools/write.py

@@ -0,0 +1,275 @@
+"""
+TODO:
+ - ContentNamespace
+"""
+import typing as ta
+
+from omlish import lang
+
+from ....tools.execution.catalog import ToolCatalogEntry
+from ....tools.execution.reflect import reflect_tool_catalog_entry
+from ....tools.reflect import tool_spec_override
+from ..context import todo_tool_context
+from ..types import TODO_ITEM_FIELD_DESCS
+from ..types import TodoItem
+
+
+##
+
+
+@tool_spec_override(
+    desc=f"""
+        Use this tool to create and manage a structured list of todo items corresponding to subtasks for your current
+        session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user. It
+        also helps the user understand the progress of the overall task and progress of their requests.
+
+        A todo item is comprised of the following fields:
+        - id: {TODO_ITEM_FIELD_DESCS['id']}
+        - content: {TODO_ITEM_FIELD_DESCS['content']}
+        - priority: {TODO_ITEM_FIELD_DESCS['priority']}
+        - status: {TODO_ITEM_FIELD_DESCS['status']}
+
+        Todo item priorities are as follows:
+        - pending: Task not yet started.
+        - in_progress: Currently working on (limit to ONE task at a time).
+        - completed: Task finished successfully.
+        - cancelled: Task no longer needed.
+
+        Manage todo items in the following manner:
+        - Update todo item status in real-time as you work.
+        - Mark todo items complete IMMEDIATELY after finishing (don't batch completions).
+        - Only have ONE todo item task in_progress at any time.
+        - Complete current todo item tasks before starting new ones.
+        - Cancel todo items that become irrelevant.
+
+        Breakdown tasks in the following manner:
+        - Create specific, actionable items.
+        - Break complex tasks into smaller, manageable steps.
+        - Use clear, descriptive task names.
+
+        Use this tool proactively in these scenarios:
+        - Complex multi-step tasks - When a task requires 3 or more distinct steps or actions.
+        - Non-trivial and complex tasks - Tasks that require careful planning or multiple operations.
+        - User explicitly requests todo list - When the user directly asks you to use the todo list.
+        - User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated).
+        - After receiving new instructions - Immediately capture user requirements as todos. Feel free to edit the todo
+          list based on new information.
+        - After completing a task - Mark it complete and add any new follow-up tasks
+        - When you start working on a new task, mark the todo item as in_progress. Ideally you should only have one todo
+          item as in_progress at a time. Complete existing tasks before starting new ones.
+
+        Skip using this tool when:
+        - There is only a single, straightforward task.
+        - The task is trivial and tracking it provides no organizational benefit.
+        - The task can be completed in less than 3 trivial steps.
+        - The task is purely conversational or informational.
+
+        You should not use this tool if there is only one trivial task to do. In this case you are better off just doing
+        the task directly.
+
+        ## Examples of WHEN to use the todo list
+
+        <example>
+            <user>
+                I want to add a dark mode toggle to the application settings. Make sure you run the tests and build when
+                you're done!
+            </user>
+            <assistant>
+                I'll help add a dark mode toggle to your application settings. Let me create a todo list to track this
+                implementation.
+            </assistant>
+            <action>
+                * Creates todo list with the following items *
+                1. Create dark mode toggle component in Settings page
+                2. Add dark mode state management (context/store)
+                3. Implement CSS-in-JS styles for dark theme
+                4. Update existing components to support theme switching
+                5. Run tests and build process, addressing any failures or errors that occur
+
+                * Begins working on the first task *
+            </action>
+            <reasoning>
+                The assistant used the todo list because:
+                - Adding dark mode is a multi-step feature requiring UI, state management, and styling changes.
+                - The user explicitly requested tests and build be run afterward.
+                - The assistant inferred that tests and build need to pass by adding "Ensure tests and build succeed" as
+                  the final task.
+            </reasoning>
+        </example>
+
+        <example>
+            <user>
+                Help me rename the function getCwd to getCurrentWorkingDirectory across my project
+            </user>
+            <assistant>
+                Let me first search through your codebase to find all occurrences of 'getCwd'.
+            </assistant>
+            <action>
+                * Uses grep or search tools to locate all instances of getCwd in the codebase *
+            </action>
+            <assistant>
+                I've found 15 instances of 'getCwd' across 8 different files. Let me create a todo list to track these
+                changes.
+            </assistant>
+            <action>
+                * Creates todo list with specific items for each file that needs updating *
+            </action>
+            <reasoning>
+                The assistant used the todo list because:
+                - First, the assistant searched to understand the scope of the task.
+                - Upon finding multiple occurrences across different files, it determined this was a complex task with
+                  multiple steps.
+                - The todo list helps ensure every instance is tracked and updated systematically.
+                - This approach prevents missing any occurrences and maintains code consistency.
+            </reasoning>
+        </example>
+
+        <example>
+            <user>
+                I need to implement these features for my e-commerce site: user registration, product catalog, shopping
+                cart, and checkout flow.
+            </user>
+            <assistant>
+                I'll help implement these features. First, let's add all the features to the todo list.
+            </assistant>
+            <action>
+                * Creates a todo list breaking down each feature into specific tasks based on the project architecture *
+            </action>
+            <assistant>
+                Let's start with user registration. This will involve creating database models, API endpoints, and
+                frontend forms that integrate with your existing authentication system.
+            </assistant>
+            <reasoning>
+                The assistant used the todo list because:
+                - The user provided multiple complex features to implement in a comma separated list.
+                - The todo list helps organize these large features into manageable tasks.
+                - This approach allows for tracking progress across the entire implementation.
+            </reasoning>
+        </example>
+
+        <example>
+            <user>
+                Can you help optimize my React application? It's rendering slowly and has performance issues.
+            </user>
+            <assistant>
+                I'll help optimize your React application. First, let me examine your codebase to identify potential
+                performance bottlenecks.
+            </assistant>
+            <action>
+                * Reviews component structure, render patterns, state management, and data fetching *
+            </action>
+            <assistant>
+                After analyzing your codebase, I've identified several performance issues. Let me create a todo list to
+                track our optimization efforts.
+            </assistant>
+            <action>
+                * Creates todo list with the following items *
+                1. Implement memoization for expensive calculations in ProductList
+                2. Add virtualization for long lists in Dashboard
+                3. Optimize image loading in Gallery component
+                4. Fix state update loops in ShoppingCart
+                5. Review bundle size and implement code splitting
+            </action>
+            <assistant>
+                Let's start by implementing memoization for the expensive calculations in your ProductList component.
+            </assistant>
+            <reasoning>
+                The assistant used the todo list because:
+                - First, the assistant examined the codebase to identify specific performance issues.
+                - Based on this analysis, it identified multiple optimization opportunities.
+                - Performance optimization is a non-trivial task requiring multiple steps.
+                - The todo list helps methodically track improvements across different components.
+                - This systematic approach ensures all performance bottlenecks are addressed.
+            </reasoning>
+        </example>
+
+        ## Examples of when NOT to use the todo list
+
+        <example>
+            <user>
+                How do I print 'Hello World' in Python?
+            </user>
+            <assistant>
+                In Python, you can print "Hello World" with this simple code:
+
+                    print("Hello World")
+
+                This will output the text "Hello World" to the console when executed.
+            </assistant>
+            <reasoning>
+                The assistant did not use the todo list because this is a single, trivial task that can be completed in
+                one step. There's no need to track multiple tasks or steps for such a straightforward request.
+            </reasoning>
+        </counter>
+
+        <example>
+            <user>
+                What does the git status command do?
+            </user>
+            <assistant>
+                The git status command shows the current state of your working directory and staging area. It displays
+                which changes have been staged, which haven't, and which files aren't being tracked by Git. This is a
+                fundamental command for understanding the current state of your repository before making commits.
+            </assistant>
+            <reasoning>
+                The assistant did not use the todo list because this is an informational request with no actual coding
+                task to complete. The user is simply asking for an explanation, not for the assistant to perform
+                multiple steps or tasks.
+            </reasoning>
+        </example>
+
+        <example>
+            <user>
+                Can you add a comment to the calculateTotal function to explain what it does?
+            </user>
+            <assistant>
+                Sure, let me add a comment to the calculateTotal function to explain what it does.
+            </assistant>
+            <action>
+                * Uses the Edit tool to add a comment to the calculateTotal function *
+            </action>
+            <reasoning>
+                The assistant did not use the todo list because this is a single, straightforward task confined to one
+                location in the code. Adding a comment doesn't require tracking multiple steps or systematic
+                organization.
+            </reasoning>
+        </example>
+
+        <example>
+            <user>
+                Run npm install for me and tell me what happens.
+            </user>
+            <assistant>
+                I'll run the npm install command for you.
+            </assistant>
+            <action>
+                * Executes: npm install *
+            </action>
+            <assistant>
+                The command completed successfully. Here's the output:
+
+                [Output of npm install command]
+
+                All dependencies have been installed according to your package.json file.
+            </assistant>
+            <reasoning>
+                The assistant did not use the todo list because this is a single command execution with immediate
+                results. There are no multiple steps to track or organize, making the todo list unnecessary for this
+                straightforward task.
+            </reasoning>
+        </example>
+
+        When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you
+        complete all requirements successfully.
+    """,
+)
+def execute_todo_write_tool(todo_items: ta.Sequence[TodoItem]) -> str:
+    ctx = todo_tool_context()
+    ctx.set_items(todo_items)
+
+    return 'Todo list updated.'
+
+
+@lang.cached_function
+def todo_write_tool() -> ToolCatalogEntry:
+    return reflect_tool_catalog_entry(execute_todo_write_tool)

ommlds/minichain/lib/todo/types.py

@@ -0,0 +1,55 @@
+"""
+TODO:
+ - enums lol
+  - * with ToolParam-like desc metadata somehow *
+"""
+import dataclasses as dc
+import typing as ta
+
+from omlish import lang
+
+from ...tools.reflect import tool_param_metadata
+from ...tools.types import ToolParam
+from ...utils import join_human_readable_str_list
+from ...utils import str_literal_values
+
+
+##
+
+
+TodoStatus: ta.TypeAlias = ta.Literal[
+    'pending',
+    'in_progress',
+    'completed',
+    'cancelled',
+]
+
+TOOL_STATUSES: ta.Sequence[str] = str_literal_values(TodoStatus)
+
+
+ToolPriority: ta.TypeAlias = ta.Literal[
+    'high',
+    'medium',
+    'low',
+]
+
+TOOL_PRIORITIES: ta.Sequence[str] = str_literal_values(ToolPriority)
+
+
+@dc.dataclass(frozen=True, kw_only=True)
+class TodoItem(lang.Final):
+    id: str = dc.field(metadata=tool_param_metadata(desc='A unique identifier for this todo item.'))
+    content: str = dc.field(metadata=tool_param_metadata(desc='A brief description of the task.'))
+    priority: ToolPriority = dc.field(metadata=tool_param_metadata(
+        desc=f'Priority of the task: {join_human_readable_str_list(map(repr, TOOL_PRIORITIES))}.',
+    ))
+
+    status: TodoStatus = dc.field(metadata=tool_param_metadata(
+        desc=f'Current status of the task: {join_human_readable_str_list(map(repr, TOOL_STATUSES))}.',
+    ))
+
+
+TODO_ITEM_FIELD_DESCS: ta.Mapping[str, str] = {
+    f.name: f.metadata[ToolParam].desc
+    for f in dc.fields(TodoItem)  # noqa
+}

ommlds/minichain/tools/execution/context.py

@@ -2,8 +2,8 @@ import contextlib
 import contextvars
 import typing as ta
 
+from omlish import check
 from omlish import collections as col
-from omlish import dataclasses as dc
 from omlish import lang
 
 
@@ -13,30 +13,34 @@ T = ta.TypeVar('T')
 ##
 
 
-@dc.dataclass(frozen=True)
 class ToolContext(lang.Final):
-    dct: col.TypeMap = col.TypeMap()
+    def __init__(self, *items: ta.Any) -> None:
+        super().__init__()
 
-    @classmethod
-    def new(cls, *objs: ta.Any) -> 'ToolContext':
-        return cls(col.TypeMap(objs))
+        self._dct: col.TypeMap = col.TypeMap(items)
+        if ToolContext in self._dct:
+            raise KeyError(ToolContext)
 
-    #
+    def __repr__(self) -> str:
+        return f'{self.__class__.__name__}<{", ".join(ic.__name__ for ic in self._dct)}>'
 
     def __len__(self) -> int:
-        return len(self.dct)
+        return len(self._dct)
 
     def __iter__(self) -> ta.Iterator[ta.Any]:
-        return iter(self.dct)
+        return iter(self._dct)
+
+    def __contains__(self, ty: type[T]) -> bool:
+        return ty in self._dct
 
     def get(self, ty: type[T]) -> T | None:
-        return self.dct.get(ty)
+        return self._dct.get(ty)
 
     def __getitem__(self, cls: type[T]) -> T:
-        return self.dct[cls]
+        return self._dct[cls]
 
     def get_any(self, cls: type | tuple[type, ...]) -> ta.Sequence[T]:
-        return self.dct.get_any(cls)
+        return self._dct.get_any(cls)
 
 
 ##
@@ -45,8 +49,24 @@ class ToolContext(lang.Final):
 _TOOL_CONTEXT: contextvars.ContextVar[ToolContext] = contextvars.ContextVar(f'{__name__}._TOOL_CONTEXT')
 
 
-@contextlib.contextmanager
-def bind_tool_context(ctx: ToolContext) -> ta.Generator[ToolContext]:
+@ta.overload
+def bind_tool_context(ctx: ToolContext) -> ta.ContextManager[ToolContext]:
+    ...
+
+
+@ta.overload
+def bind_tool_context(*items: ta.Any) -> ta.ContextManager[ToolContext]:
+    ...
+
+
+@contextlib.contextmanager  # type: ignore[misc]
+def bind_tool_context(*args):
+    if args and isinstance(args[0], ToolContext):
+        check.arg(len(args) == 1)
+        ctx = args[0]
+    else:
+        ctx = ToolContext(*args)
+
     try:
         cur = _TOOL_CONTEXT.get()
     except LookupError:

ommlds/minichain/tools/execution/errors.py

@@ -0,0 +1,15 @@
+import abc
+
+from omlish import lang
+
+from ...content.materialize import CanContent
+
+
+##
+
+
+class ToolExecutionError(Exception, lang.Abstract):
+    @property
+    @abc.abstractmethod
+    def content(self) -> CanContent:
+        raise NotImplementedError

ommlds/minichain/tools/execution/reflect.py

@@ -1,6 +1,3 @@
-"""
-TODO:
-"""
 import inspect
 import typing as ta
 

ommlds/minichain/tools/jsonschema.py

@@ -9,6 +9,7 @@ from ..content.prepare import default_content_str_preparer
 from .types import EnumToolDtype
 from .types import MappingToolDtype
 from .types import NullableToolDtype
+from .types import ObjectToolDtype
 from .types import PrimitiveToolDtype
 from .types import SequenceToolDtype
 from .types import ToolDtype
@@ -72,6 +73,15 @@ class ToolJsonschemaRenderer:
                 'enum': list(t.values),
             }
 
+        if isinstance(t, ObjectToolDtype):
+            return {
+                'type': 'object',
+                'properties': {
+                    k: self.render_type(v)
+                    for k, v in t.fields.items()
+                },
+            }
+
         raise TypeError(t)
 
     def render_tool_params(self, ts: ToolSpec) -> dict:
@@ -98,7 +108,7 @@ class ToolJsonschemaRenderer:
         }
 
     def render_tool(self, ts: ToolSpec) -> dict:
-        pa_dct = self.render_tool_params(ts)
+        pa_dct = self.render_tool_params(ts) if ts.params else None
 
         ret_dct = {
             **({'description': self._content_str_preparer.prepare_str(ts.returns_desc)} if ts.returns_desc is not None else {}),  # noqa

ommlds/minichain/tools/reflect.py

@@ -23,9 +23,11 @@ from omlish import metadata as md
 from omlish import reflect as rfl
 from omlish.lite.cached import cached_nullary
 
+from ..content.materialize import CanContent
 from .types import EnumToolDtype
 from .types import MappingToolDtype
 from .types import NullableToolDtype
+from .types import ObjectToolDtype
 from .types import PrimitiveToolDtype
 from .types import SequenceToolDtype
 from .types import ToolDtype
@@ -108,6 +110,12 @@ class ToolReflector:
     ])
 
     def reflect_type(self, rty: rfl.Type) -> ToolDtype:
+        if isinstance(rty, type) and dc.is_dataclass(rty):
+            return ObjectToolDtype({
+                f.name: self.reflect_type(rfl.type_(f.type))
+                for f in dc.fields(rty)
+            })
+
         if isinstance(rty, (type, rfl.Any)):
             return PrimitiveToolDtype.of(rty)
 
@@ -160,14 +168,22 @@ class ToolReflector:
 
         #
 
+        p_ovr_dct: dict[str, dict[str, ta.Any]] = {}
         ts_ovr: dict[str, ta.Any] = {}
+        o: _ToolSpecOverride
         for o in md.get_object_metadata(fn, type=_ToolSpecOverride):
-            # TODO: better params handling / merging
             ts_ovr.update({
                 k: v
                 for k, v in dc.asdict(o).items()
-                if v is not None
+                if k != 'params'
+                and v is not None
             })
+            for op in (o.params or []):
+                p_ovr_dct.setdefault(check.non_empty_str(op.name), {}).update({
+                    k: v
+                    for k, v in dc.asdict(op).items()
+                    if v is not None
+                })
 
         #
 
@@ -207,23 +223,39 @@ class ToolReflector:
         if 'params' not in ts_kw:
             ds_p_dct = {
                 ds_p.arg_name: ds_p
-                for ds_p in (ds.params if ds is not None else [])
+                for ds_p in (ds.params if ds is not None else {})
             }
 
-            params: dict[str, ToolParam] = {}
-            for sig_p in sig().parameters.values():
-                check.not_in(sig_p.name, params)
-
-                ds_p = ds_p_dct.get(sig_p.name)
-
-                params[sig_p.name] = ToolParam(
-                    sig_p.name,
+            sig_p_dct = sig().parameters
 
-                    desc=self._prepare_desc(ds_p.description) if ds_p is not None else None,
+            pns: list[str] = list({**p_ovr_dct, **ds_p_dct, **sig_p_dct})
 
-                    type=self.reflect_type(rfl.type_(th()[sig_p.name])) if sig_p.name in th() else None,
-
-                    required=sig_p.default is inspect.Parameter.empty,
+            params: dict[str, ToolParam] = {}
+            for pn in pns:
+                ovr_p = p_ovr_dct.get(pn, {})
+                ds_p = ds_p_dct.get(pn)
+                sig_p = sig_p_dct.get(pn)
+
+                p_desc: CanContent
+                if (p_desc := ovr_p.get('desc')) is None:
+                    if ds_p is not None:
+                        p_desc = ds_p.description
+
+                p_type: ToolDtype | None
+                if (p_type := ovr_p.get('type')) is None:
+                    if sig_p is not None and sig_p.name in th():
+                        p_type = self.reflect_type(rfl.type_(th()[sig_p.name]))
+
+                p_required: bool | None
+                if (p_required := ovr_p.get('required')) is None:
+                    if sig_p is not None:
+                        p_required = sig_p.default is inspect.Parameter.empty
+
+                params[pn] = ToolParam(
+                    pn,
+                    desc=self._prepare_desc(p_desc) if p_desc is not None else None,
+                    type=p_type,
+                    required=p_required,
                 )
 
             ts_kw.update(params=tuple(params.values()) if params else None)

ommlds/minichain/tools/types.py

@@ -127,6 +127,15 @@ class EnumToolDtype(ToolDtype):
     values: ta.Sequence[ta.Any]
 
 
+#
+
+
+@dc.dataclass(frozen=True)
+@dc.extra_class_params(terse_repr=True)
+class ObjectToolDtype(ToolDtype):
+    fields: ta.Mapping[str, ToolDtype]
+
+
 ##
 
 

ommlds/minichain/utils.py

@@ -0,0 +1,27 @@
+import typing as ta
+
+from omlish import check
+from omlish import reflect as rfl
+
+
+##
+
+
+def join_human_readable_str_list(
+        strs: ta.Iterable[str],
+        *,
+        sep: str = ', ',
+        disj: str = 'or ',
+) -> str:
+    seq = list(strs)
+    return sep.join(
+        (disj if i == len(seq) - 1 else '') + s
+        for i, s in enumerate(seq)
+    )
+
+
+##
+
+
+def str_literal_values(lit: ta.Any) -> ta.Sequence[str]:
+    return tuple(check.isinstance(rfl.type_(lit), rfl.Literal).args)

{ommlds-0.0.0.dev448.dist-info → ommlds-0.0.0.dev450.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ommlds
-Version: 0.0.0.dev448
+Version: 0.0.0.dev450
 Summary: ommlds
 Author: wrmsr
 License-Expression: BSD-3-Clause
@@ -14,8 +14,8 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: omdev==0.0.0.dev448
-Requires-Dist: omlish==0.0.0.dev448
+Requires-Dist: omdev==0.0.0.dev450
+Requires-Dist: omlish==0.0.0.dev450
 Provides-Extra: all
 Requires-Dist: llama-cpp-python~=0.3; extra == "all"
 Requires-Dist: mlx~=0.29; extra == "all"