GoaLT - Greatest of All Linear Time

    GoaLT is a goal defining library using rules and measurements to define and measure goals.
    
    ## Features
    
    - Define goals with target values and units
    - Track measurements over time with automatic progress calculation
    - Rule-based evaluation (threshold, deadline, minimum, maximum)
    - Anti-goals to track what should be avoided
    - Process boundaries for limits and constraints
    - Status tracking (draft, active, achieved, failed, abandoned)
    - GoalManager for coordinated goal management
    - Planning modules (HTN, PDDL, GOAP)
    - Integration with Metrologic for statistics
    - Integration with Owl for ML aggregation
    - Integration with MindOT for decision making
    
    
    #TODO: integrat the following into the README.md
    - [] Evaluator vs Executor...evaluator reviews available information  in furtherence of goal
         Executor actively looks for information relative to the goal to ensure it has been achieved
    
    
    ## Installation
    
    ```bash
    pip install goalt
    ```
    
    ## Quick Start
    
    ```python
    from goalt import Goal, GoalDefinition, Measurement, GoalStatus
    
    # Define a goal
    definition = GoalDefinition(
        name="Run Marathon",
        description="Complete a marathon in under 4 hours",
        target_value=42.195,
        unit="km"
    )
    
    # Create goal instance
    goal = Goal(definition=definition)
    goal.activate()
    
    # Add measurements
    goal.definition.add_measurement(Measurement(name="distance", value=5.0, unit="km"))
    goal.definition.add_measurement(Measurement(name="distance", value=10.0, unit="km"))
    
    # Check progress
    print(f"Progress: {goal.progress:.1f}%")  # Progress: 23.7%
    ```
    
    ## Examples
    
    ### 1. Basic Goal with Manual Measurements
    
    ```python
    from goalt import Goal, GoalDefinition, Measurement
    
    # Define a fitness goal
    definition = GoalDefinition(
        name="Weight Loss Goal",
        description="Lose 10 kg in 3 months",
        target_value=10.0,
        unit="kg"
    )
    
    goal = Goal(definition=definition)
    goal.activate()
    
    # Track weekly progress
    goal.definition.add_measurement(Measurement(name="weight_lost", value=2.0, unit="kg"))
    goal.definition.add_measurement(Measurement(name="weight_lost", value=4.5, unit="kg"))
    goal.definition.add_measurement(Measurement(name="weight_lost", value=7.0, unit="kg"))
    
    print(f"Current progress: {goal.progress:.1f}%")  # 70.0%
    print(f"Status: {goal.status.value}")  # active
    ```
    
    ### 2. Goal with Threshold Rules
    
    ```python
    from goalt import Goal, GoalDefinition, GoalEvaluator, Measurement
    
    # Define a sales goal with threshold
    definition = GoalDefinition(
        name="Q1 Sales Target",
        description="Achieve $100,000 in sales by end of Q1",
        target_value=100000.0,
        unit="USD",
        rules=[
            {
                "type": "threshold",
                "condition": "gte",
                "value": 100000.0,
                "message": "Must achieve at least $100,000 in sales"
            }
        ]
    )
    
    goal = Goal(definition=definition)
    goal.activate()
    
    # Add sales measurements
    goal.definition.add_measurement(Measurement(name="sales", value=35000.0, unit="USD"))
    goal.definition.add_measurement(Measurement(name="sales", value=78000.0, unit="USD"))
    goal.definition.add_measurement(Measurement(name="sales", value=105000.0, unit="USD"))
    
    # Evaluate the goal
    evaluator = GoalEvaluator()
    evaluation = evaluator.evaluate(goal)
    
    print(f"Progress: {evaluation.progress_percent:.1f}%")  # 105.0%
    print(f"Result: {evaluation.overall_result.value}")  # passed
    print(f"Current value: ${evaluation.current_value:,.2f}")  # $105,000.00
    ```
    
    ### 3. Goal with Deadline
    
    ```python
    from goalt import Goal, GoalDefinition, GoalEvaluator, Measurement
    from datetime import datetime, timedelta
    
    # Define a project completion goal with deadline
    deadline = (datetime.now() + timedelta(days=30)).isoformat()
    
    definition = GoalDefinition(
        name="Project Launch",
        description="Launch product by end of month",
        target_value=100.0,
        unit="percent",
        rules=[
            {
                "type": "threshold",
                "condition": "gte",
                "value": 100.0,
                "message": "Project must be 100% complete"
            },
            {
                "type": "deadline",
                "date": deadline,
                "message": f"Must complete by {deadline}"
            }
        ]
    )
    
    goal = Goal(definition=definition)
    goal.activate()
    
    # Track completion
    goal.definition.add_measurement(Measurement(name="completion", value=85.0, unit="percent"))
    
    # Evaluate
    evaluator = GoalEvaluator()
    evaluation = evaluator.evaluate(goal)
    
    print(f"Progress: {evaluation.progress_percent:.1f}%")  # 85.0%
    print(f"Passed rules: {evaluation.passed_rules_count}/{evaluation.total_rules_count}")
    ```
    
    ### 4. Anti-Goals (Things to Avoid)
    
    ```python
    from goalt import AntiGoal, AntiGoalDefinition, Measurement
    
    # Define an anti-goal for response time
    definition = AntiGoalDefinition(
        name="Response Time Limit",
        description="API response time must not exceed 200ms",
        max_threshold=200.0,
        unit="ms",
        penalty_per_violation=5.0,
        rules=[
            {
                "type": "maximum",
                "value": 200.0,
                "message": "Response time must not exceed 200ms"
            }
        ]
    )
    
    anti_goal = AntiGoal(definition=definition)
    anti_goal.activate()
    
    # Add measurements
    anti_goal.definition.add_measurement(Measurement(name="response_time", value=150.0, unit="ms"))
    anti_goal.definition.add_measurement(Measurement(name="response_time", value=250.0, unit="ms"))
    
    # Check violation
    current_value = anti_goal.definition.get_latest_value()
    is_violated = anti_goal.definition.is_violated(current_value)
    penalty = anti_goal.definition.get_score(current_value)
    
    print(f"Violated: {is_violated}")  # True
    print(f"Penalty: {penalty}")  # 5.0
    print(f"Severity: {anti_goal.definition.get_severity(current_value)}")  # low
    ```
    
    ### 5. Process Boundaries
    
    ```python
    from goalt import ProcessBoundary, Measurement
    
    # Define a time boundary for deployment
    boundary = ProcessBoundary(
        name="Deployment Time Limit",
        description="Deployment must complete within 5 minutes",
        boundary_type="time",
        limit_value=300.0,
        unit="seconds",
        enforce=True,
        penalty_score=10.0,
        warning_threshold=0.8,  # Warn at 80%
        critical_threshold=0.95  # Critical at 95%
    )
    
    # Add measurements
    boundary.add_measurement(Measurement(name="deployment_time", value=180.0, unit="seconds"))
    boundary.add_measurement(Measurement(name="deployment_time", value=250.0, unit="seconds"))
    
    current = boundary.get_latest_value()
    
    print(f"Current: {current}s / {boundary.limit_value}s")
    print(f"Warning: {boundary.is_warning(current)}")  # True (250/300 = 83%)
    print(f"Critical: {boundary.is_critical(current)}")  # False
    print(f"Violated: {boundary.is_violated(current)}")  # False
    print(f"Penalty: {boundary.get_penalty(current)}")  # 0.0
    ```
    
    ### 6. Using GoalManager
    
    ```python
    from goalt import create_goal_manager, Measurement
    
    # Create a manager with deployment preset
    manager = create_goal_manager(preset="deployment")
    
    # Goals, anti-goals, and boundaries are pre-configured
    # Activate them
    manager.activate_goal("deployment_success")
    manager.activate_goal("tests_pass")
    manager.activate_anti_goal("no_security_vulnerabilities")
    
    # Add measurements
    manager.add_measurement_to_goal(
        "tests_pass",
        Measurement(name="test_pass_rate", value=95.0, unit="percent")
    )
    
    manager.add_measurement_to_anti_goal(
        "no_security_vulnerabilities",
        Measurement(name="vulnerabilities", value=0.0, unit="vulnerabilities")
    )
    
    # Get compliance score
    score = manager.get_compliance_score()
    
    print(f"Goal Score: {score['goal_score']:.1f}")
    print(f"Total Penalty: {score['total_penalty']:.1f}")
    print(f"Compliance: {score['compliance_score']:.1f}")
    print(f"Active Goals: {score['active_goals']}")
    print(f"Achieved Goals: {score['achieved_goals']}")
    ```
    
    ### 7. Custom Goal Manager
    
    ```python
    from goalt import GoalManager, Measurement
    
    # Create custom manager
    manager = GoalManager()
    
    # Create custom goals
    manager.create_goal(
        name="Code Coverage",
        description="Achieve 90% code coverage",
        target_value=90.0,
        unit="percent",
        weight=1.5,
        priority=1,
        tags=["quality", "testing"]
    )
    
    manager.create_anti_goal(
        name="Bug Escape Rate",
        description="Keep bugs in production under 5%",
        max_threshold=5.0,
        unit="percent",
        penalty=8.0,
        weight=2.0,
        tags=["quality", "bugs"]
    )
    
    manager.create_boundary(
        name="Build Time",
        description="Build must complete in under 10 minutes",
        boundary_type="time",
        limit_value=600.0,
        unit="seconds",
        penalty=3.0
    )
    
    # Activate and measure
    manager.activate_goal("Code Coverage")
    manager.add_measurement_to_goal(
        "Code Coverage",
        Measurement(name="coverage", value=87.0, unit="percent")
    )
    
    # Check boundaries
    boundary_status = manager.check_boundaries()
    print(boundary_status)
    ```
    
    ### 8. Generating Reports
    
    ```python
    from goalt import Goal, GoalDefinition, Measurement, generate_report
    
    # Create multiple goals
    goals = []
    
    for i, (name, target) in enumerate([
        ("Sprint 1 Velocity", 40.0),
        ("Sprint 2 Velocity", 45.0),
        ("Sprint 3 Velocity", 50.0)
    ]):
        definition = GoalDefinition(
            name=name,
            description=f"Achieve {target} story points",
            target_value=target,
            unit="points"
        )
        goal = Goal(definition=definition)
        goal.activate()
    
        # Simulate progress
        goal.definition.add_measurement(
            Measurement(name="velocity", value=target * 0.9, unit="points")
        )
        goals.append(goal)
    
    # Generate comprehensive report
    report = generate_report(goals)
    
    # Export as JSON
    print(report.to_json(indent=2))
    
    # Export as Markdown
    print(report.to_markdown())
    
    # Access summary
    print(f"\nSummary:")
    print(f"Total: {report.summary['total_goals']}")
    print(f"Passed: {report.summary['passed']}")
    print(f"Failed: {report.summary['failed']}")
    print(f"Success Rate: {report.summary['success_rate']:.1f}%")
    ```
    
    ## CLI Usage
    
    ```bash
    # Create a new goal
    goalt create "Run Marathon" -d "Complete a marathon" -t 42.195 -u "km"
    
    # Record a measurement
    goalt measure "Run Marathon" -v 10.0 -u "km"
    
    # Check status
    goalt status "Run Marathon"
    
    # List all goals
    goalt list-goals
    ```
    
    ## Development
    
    ```bash
    # Install development dependencies
    pip install -e ".[dev]"
    
    # Run tests
    pytest
    
    # Run with coverage
    pytest --cov=goalt tests/
    ```
    
    ## License
    
    MIT License - see LICENSE file for details.