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

ommlds/minichain/lib/todo/context.py

@@ -0,0 +1,27 @@
+import typing as ta
+
+from ...tools.execution.context import tool_context
+from .types import TodoItem
+
+
+##
+
+
+class TodoContext:
+    def __init__(
+            self,
+            items: ta.Sequence[TodoItem] | None = None,
+    ) -> None:
+        super().__init__()
+
+        self._items = items
+
+    def get_items(self) -> ta.Sequence[TodoItem] | None:
+        return self._items
+
+    def set_items(self, items: ta.Sequence[TodoItem] | None) -> None:
+        self._items = list(items) if items is not None else None
+
+
+def todo_tool_context() -> TodoContext:
+    return tool_context()[TodoContext]

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

@@ -0,0 +1,39 @@
+from omlish import lang
+from omlish.formats import json
+
+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
+
+
+##
+
+
+@tool_spec_override(
+    desc="""
+        Use this tool to read the current todo list for your current session. This tool should be used proactively and
+        frequently to ensure that you are aware of the status of the current subtask list.
+
+        You should make use of this tool often, especially in the following situations:
+        - At the beginning of conversations to see what's pending.
+        - Before starting new tasks to prioritize work.
+        - When the user asks about previous tasks or plans.
+        - Whenever you're uncertain about what to do next.
+        - After completing tasks to update your understanding of remaining work.
+        - After every few messages to ensure you're on track.
+
+        Usage:
+        - Returns a list of todo items in json format with their id, status, priority, and content.
+        - Use this information to track progress and plan next steps.
+    """,
+)
+def execute_todo_read_tool() -> str:
+    ctx = todo_tool_context()
+
+    return json.dumps_compact(ctx.get_items() or [])
+
+
+@lang.cached_function
+def todo_read_tool() -> ToolCatalogEntry:
+    return reflect_tool_catalog_entry(execute_todo_read_tool)

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/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

@@ -27,6 +27,7 @@ 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
@@ -109,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)
 

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.dev449.dist-info → ommlds-0.0.0.dev450.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ommlds
-Version: 0.0.0.dev449
+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.dev449
-Requires-Dist: omlish==0.0.0.dev449
+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"