scopemate 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

scopemate/task_analysis.py

@@ -15,11 +15,30 @@ def check_and_update_parent_estimates(tasks: List[ScopeMateTask]) -> List[ScopeM
     """
     Check and update parent task estimates based on child task complexity.
     
+    This function ensures consistency in the task hierarchy by making sure that 
+    parent tasks have appropriate size and time estimates relative to their children.
+    If a child task has a higher complexity or longer time estimate than its parent,
+    the parent's estimates are automatically increased to maintain logical consistency.
+    
+    The function works by:
+    1. Creating maps of task IDs to task objects and parent IDs
+    2. Computing complexity values for all tasks based on their size and time estimates
+    3. Identifying inconsistencies where child tasks have higher complexity than parents
+    4. Updating parent estimates to match or exceed their children's complexity
+    5. Recursively propagating updates up the task hierarchy to maintain consistency
+    
     Args:
-        tasks: List of ScopeMateTask objects
+        tasks: List of ScopeMateTask objects to analyze and update
         
     Returns:
-        Updated list of ScopeMateTask objects
+        Updated list of ScopeMateTask objects with consistent parent-child estimates
+        
+    Example:
+        ```python
+        # Before: parent task has "straightforward" size but child has "complex" size
+        updated_tasks = check_and_update_parent_estimates(tasks)
+        # After: parent task is updated to "complex" or higher to maintain consistency
+        ```
     """
     # Create a map of tasks by ID for easy access
     task_map = {t.id: t for t in tasks}
@@ -229,14 +248,36 @@ def should_decompose_task(task: ScopeMateTask, depth: int, max_depth: int, is_le
     """
     Determine if a task should be broken down based on complexity and time estimates.
     
+    This function applies a set of heuristics to decide whether a task needs further
+    decomposition. The decision is based on multiple factors:
+    
+    1. Task depth in the hierarchy - tasks at or beyond max_depth are never decomposed
+    2. Task complexity - "complex", "uncertain", or "pioneering" tasks should be broken down
+    3. Time estimate - tasks with long durations should be broken down into smaller units
+    4. Leaf status - whether the task already has subtasks
+    
+    The breakdown logic implements a graduated approach where:
+    - Very complex tasks are always broken down (unless at max depth)
+    - Long duration tasks are broken down, especially if they're leaf tasks
+    - Tasks with "week" duration are broken down up to max_depth
+    - Tasks at depth 2+ with "sprint" duration aren't broken down (unless they're "multi-sprint")
+    
     Args:
         task: The ScopeMateTask to evaluate
-        depth: Current depth in the task hierarchy
-        max_depth: Maximum allowed depth
-        is_leaf: Whether this is a leaf task (has no children)
+        depth: Current depth in the task hierarchy (0 for root tasks)
+        max_depth: Maximum allowed depth for the task hierarchy
+        is_leaf: Whether this task currently has no children
         
     Returns:
-        True if the task should be broken down, False otherwise
+        True if the task should be broken down into subtasks, False otherwise
+        
+    Example:
+        ```python
+        task = get_task_by_id("TASK-123")
+        depth = get_task_depth(task, task_depths, tasks)
+        if should_decompose_task(task, depth, max_depth=5, is_leaf=True):
+            subtasks = suggest_breakdown(task)
+        ```
     """
     # Always respect max depth limit
     if depth >= max_depth:

{scopemate-0.1.0.dist-info → scopemate-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scopemate
-Version: 0.1.0
+Version: 0.2.0
 Summary: 🪜 A CLI tool for Purpose/Scope/Outcome planning
 Author: Anoop Thomas Mathew
 Author-email: Anoop Thomas Mathew <atmb4u@gmail.com>
@@ -24,6 +24,10 @@ License-File: LICENSE
 Requires-Dist: openai>=1.0.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: twine>=6.1.0
+Requires-Dist: google-generativeai>=0.3.0
+Requires-Dist: anthropic>=0.12.0
+Requires-Dist: ipython>=8.35.0
+Requires-Dist: ipdb>=0.13.13
 Dynamic: author
 Dynamic: license-file
 Dynamic: requires-python
@@ -78,11 +82,15 @@ Scopemate is built around a three-part framework for strategic decision making:
 - Pydantic validation
 - Cross-platform support (Windows, macOS, Linux)
 - Works with Python 3.10 and above
+- Automatic Markdown export of plans for easy sharing
 
 ## Requirements
 
 - Python 3.10 or higher
-- OpenAI API key set as environment variable (`OPENAI_API_KEY`)
+- An API key for one of the supported LLM providers:
+  - OpenAI API key (default)
+  - Google AI (Gemini) API key
+  - Anthropic (Claude) API key
 
 ## Installation
 
@@ -133,26 +141,123 @@ cd scopemate
 pip install -e .
 ```
 
-### Setting up the OpenAI API Key
+### Setting up API Keys
 
-scopemate requires an OpenAI API key to function. Set it as an environment variable:
+scopemate now supports multiple LLM providers. Set up the API key for your preferred provider:
 
-#### macOS/Linux
+#### OpenAI (Default)
+
+Set the OpenAI API key as an environment variable:
+
+##### macOS/Linux
 ```bash
 export OPENAI_API_KEY=your-api-key-here
 ```
 
-#### Windows Command Prompt
+##### Windows Command Prompt
 ```cmd
 set OPENAI_API_KEY=your-api-key-here
 ```
 
-#### Windows PowerShell
+##### Windows PowerShell
 ```powershell
 $env:OPENAI_API_KEY = "your-api-key-here"
 ```
 
-For permanent setup, add this to your shell profile or environment variables.
+#### Google AI (Gemini)
+
+Set the Google AI API key as an environment variable:
+
+##### macOS/Linux
+```bash
+export GEMINI_API_KEY=your-api-key-here
+```
+
+##### Windows Command Prompt
+```cmd
+set GEMINI_API_KEY=your-api-key-here
+```
+
+##### Windows PowerShell
+```powershell
+$env:GEMINI_API_KEY = "your-api-key-here"
+```
+
+#### Anthropic (Claude)
+
+Set the Anthropic API key as an environment variable:
+
+##### macOS/Linux
+```bash
+export ANTHROPIC_API_KEY=your-api-key-here
+```
+
+##### Windows Command Prompt
+```cmd
+set ANTHROPIC_API_KEY=your-api-key-here
+```
+
+##### Windows PowerShell
+```powershell
+$env:ANTHROPIC_API_KEY = "your-api-key-here"
+```
+
+### Selecting LLM Provider
+
+You can select which LLM provider to use by setting the `SCOPEMATE_LLM_PROVIDER` environment variable:
+
+#### macOS/Linux
+```bash
+# Use OpenAI (default)
+export SCOPEMATE_LLM_PROVIDER=OPENAI
+
+# Use Gemini
+export SCOPEMATE_LLM_PROVIDER=GEMINI
+
+# Use Claude
+export SCOPEMATE_LLM_PROVIDER=CLAUDE
+```
+
+#### Windows Command Prompt
+```cmd
+# Use OpenAI (default)
+set SCOPEMATE_LLM_PROVIDER=OPENAI
+
+# Use Gemini
+set SCOPEMATE_LLM_PROVIDER=GEMINI
+
+# Use Claude
+set SCOPEMATE_LLM_PROVIDER=CLAUDE
+```
+
+#### Windows PowerShell
+```powershell
+# Use OpenAI (default)
+$env:SCOPEMATE_LLM_PROVIDER = "OPENAI"
+
+# Use Gemini
+$env:SCOPEMATE_LLM_PROVIDER = "GEMINI"
+
+# Use Claude
+$env:SCOPEMATE_LLM_PROVIDER = "CLAUDE"
+```
+
+### Selecting Model
+
+You can also specify which model to use for each provider:
+
+```bash
+# OpenAI model (default is o4-mini)
+export SCOPEMATE_OPENAI_MODEL=gpt-4-turbo
+
+# Gemini model (default is gemini-flash)
+export SCOPEMATE_GEMINI_MODEL=gemini-2.0-flash
+
+# Claude model (default is claude-3-haiku-20240307)
+export SCOPEMATE_CLAUDE_MODEL=claude-3-7-sonnet-20250219
+```
+
+For permanent setup, add these environment variables to your shell profile or system environment variables.
 
 ## Usage
 
@@ -171,11 +276,10 @@ scopemate --help
 
 # Generate a project plan with purpose and outcome
 scopemate --purpose="Build a REST API for user management" --outcome="A documented API with authentication and user CRUD operations" --output="project_plan.json"
-
-# Fix inconsistent estimates in an existing plan
-scopemate --fix-estimates --input="project_plan.json" --output="fixed_plan.json"
 ```
 
+**Note:** A Markdown version of the output is automatically generated alongside the JSON file. For example, if you specify `--output="project_plan.json"`, a file named `project_plan.md` will also be created.
+
 ### Interactive Mode Workflow
 
 The interactive mode (`scopemate --interactive`) will guide you through:
@@ -205,7 +309,9 @@ The interactive mode (`scopemate --interactive`) will guide you through:
 
 ### Output Format
 
-scopemate generates a structured JSON output with the following format:
+scopemate generates both JSON and Markdown output files:
+
+1. **JSON Output** - Structured data format with the following structure:
 
 ```json
 {
@@ -245,6 +351,14 @@ scopemate generates a structured JSON output with the following format:
 }
 ```
 
+2. **Markdown Output** - Human-readable format automatically generated with the same basename as the JSON file. The Markdown output includes:
+   - A summary of the plan with task counts and complexity breakdown
+   - Hierarchical task structure preserving parent-child relationships
+   - All relevant task details formatted for easy reading
+   - Properly formatted sections for purpose, scope, outcome, and metadata
+
+This dual output approach makes it easy to both process the data programmatically (using the JSON) and share the plan with team members (using the Markdown).
+
 ### Integrating with Other Tools
 
 You can use scopemate's JSON output with other project management tools:
@@ -295,6 +409,23 @@ uv pip install -r requirements-dev.txt
 uv pip install -e .
 ```
 
+#### Using pipx
+
+[pipx](https://github.com/pypa/pipx) is useful for installing and running Python applications in isolated environments:
+
+```bash
+# Install pipx if you don't have it
+pip install pipx
+
+# Clone the repository
+git clone https://github.com/atmb4u/scopemate.git
+cd scopemate
+
+# Install the package in development mode with force flag
+# This is useful when making changes and wanting to test the CLI immediately
+pipx install --force .
+```
+
 ### Running Tests
 
 ```bash

scopemate-0.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+scopemate/__init__.py,sha256=xp32RvKQnWl1JCBMwuDsSDYg8awCryN2iBWSpJVB2es,472
+scopemate/__main__.py,sha256=nPNZe_QEoOHQ_hXf17w72BHz1UFPKuW2g3whTLwuM8E,195
+scopemate/breakdown.py,sha256=mwIDzf7m2GHVkDrRmMyeS8v2pNd99U3vlcPCtOajvs0,21048
+scopemate/cli.py,sha256=qh6iFleQc8Bld0iptyUgRm5Ga3GtZsvE6Y-q6vbm3dk,6891
+scopemate/core.py,sha256=wpXCpb5Kdpqul9edNCx2Da94137XCc1w-3KQc9-Tf3s,700
+scopemate/engine.py,sha256=8yQoxSECJCGuNSIwS-qFoaOGM1iaZ-y4Lo7k5Q6v-mk,16992
+scopemate/interaction.py,sha256=SeqQVME0MATK-m-M7T9nNHkcJ_VCRhlqydL_vQaSMWk,10893
+scopemate/llm.py,sha256=DLa2cL4pTYjnUG__gS_Lfifx3Mnpfm2QACpJSO9ooJo,23038
+scopemate/models.py,sha256=Q3SUoHu_4RejDAocEr83I00wGvxhDoJ1COVqjPsr4DQ,7738
+scopemate/storage.py,sha256=uV1-7IdwJwBENeNoO9Y3WwUUXd-jA2NvKdiERGGhmV8,11642
+scopemate/task_analysis.py,sha256=Mic0FOOy_BWI1_5TQmh__39miOcZBZ7mTUcCkv1DvkI,14967
+scopemate-0.2.0.dist-info/licenses/LICENSE,sha256=4fqQFK5AkkXmg6FBG9Wr06gCR7BMQl02TvsPYt-YL6s,1076
+scopemate-0.2.0.dist-info/METADATA,sha256=35WLUUsU01syRayWxXrx5Lt-bOqHwY31FBplRN9wCJ8,13835
+scopemate-0.2.0.dist-info/WHEEL,sha256=pxyMxgL8-pra_rKaQ4drOZAegBVuX-G_4nRHjjgWbmo,91
+scopemate-0.2.0.dist-info/entry_points.txt,sha256=XXusGEDxI6NlrYmSBcPDtjV3QvsHWVWPSrt4zD4UcLg,49
+scopemate-0.2.0.dist-info/top_level.txt,sha256=riMrI_jMCfZMb7-ecWBwqOBLdUsnPOxSu2Pgvqx7Too,10
+scopemate-0.2.0.dist-info/RECORD,,

{scopemate-0.1.0.dist-info → scopemate-0.2.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (78.1.1)
+Generator: setuptools (79.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

scopemate-0.1.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-scopemate/__init__.py,sha256=3cyRjjI2wC2pG8VeXONVOrow_dJMKUCzre8EtYfrV0s,472
-scopemate/__main__.py,sha256=nPNZe_QEoOHQ_hXf17w72BHz1UFPKuW2g3whTLwuM8E,195
-scopemate/breakdown.py,sha256=lasv2Gt1yziE_GV4DgCBWVg3TIPuggT3Tf77ny5n7Iw,19650
-scopemate/cli.py,sha256=o05Od9NEP76sQRegc3dqs-d-DCpYip2KC1GXjriiCZQ,5059
-scopemate/core.py,sha256=wpXCpb5Kdpqul9edNCx2Da94137XCc1w-3KQc9-Tf3s,700
-scopemate/engine.py,sha256=wlE39lzKoJthi6twestlyEqvEjqNEXQYvNTOfT4aGZw,9521
-scopemate/interaction.py,sha256=qWFU3QM_KPwaGdh4Rw7ewCIeYiT6Wa_H9e6bnmNoJzw,9531
-scopemate/llm.py,sha256=hD37Mk54kchdECKYmCNF3yxg0U-vW-h4y8tpNghlS3Q,14031
-scopemate/models.py,sha256=ZvFn8iegMDgCgoLjvWxj7_C7XLDWrgkF8ySuktfRaqw,4962
-scopemate/storage.py,sha256=lloD_2f2E3q_inHLiL9Kp8F_tyeerG45_rSLKXvGh4Y,3102
-scopemate/task_analysis.py,sha256=I-tH62MfYAwlHbLonjlPKBGa-X_II9QqpWS_OsjLaxU,12644
-scopemate-0.1.0.dist-info/licenses/LICENSE,sha256=4fqQFK5AkkXmg6FBG9Wr06gCR7BMQl02TvsPYt-YL6s,1076
-scopemate-0.1.0.dist-info/METADATA,sha256=Wmb1wOEmCkigLUXIS0d1BujGzV0uTpx9IpNIvyrtIJI,10557
-scopemate-0.1.0.dist-info/WHEEL,sha256=lTU6B6eIfYoiQJTZNc-fyaR6BpL6ehTzU3xGYxn2n8k,91
-scopemate-0.1.0.dist-info/entry_points.txt,sha256=XXusGEDxI6NlrYmSBcPDtjV3QvsHWVWPSrt4zD4UcLg,49
-scopemate-0.1.0.dist-info/top_level.txt,sha256=riMrI_jMCfZMb7-ecWBwqOBLdUsnPOxSu2Pgvqx7Too,10
-scopemate-0.1.0.dist-info/RECORD,,