pydsa-engine 0.1.0__py3-none-any.whl

pydsa/__init__.py

@@ -0,0 +1,182 @@
+"""
+pydsa
+~~~~~
+A semantic DSA execution engine.
+
+Quickstart
+----------
+>>> from pydsa import solve, search, info
+>>>
+>>> # Solve by natural description
+>>> result = solve("find maximum water between vertical lines", [1,8,6,2,5,4,8,3,7])
+>>> print(result.answer)           # 49
+>>> print(result.time_complexity)  # O(n)
+>>>
+>>> # Solve by exact problem id
+>>> result = solve(11, [1,8,6,2,5,4,8,3,7])
+>>>
+>>> # Browse problems
+>>> problems = search("sliding window")
+>>> for p in problems:
+...     print(p.id, p.name)
+>>>
+>>> # Get metadata for a problem
+>>> p = info("two sum")
+>>> print(p.difficulty, p.tags)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydsa.core.models   import Problem, Result
+from pydsa.core.router   import find, search as _search
+from pydsa.core.engine   import execute
+from pydsa.core          import registry as _registry
+from pydsa.core.exceptions import (
+    PyDSAError,
+    ProblemNotFoundError,
+    AmbiguousQueryError,
+    InvalidInputError,
+    SolverError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "solve",
+    "search",
+    "info",
+    "list_problems",
+    "stats",
+    # models
+    "Problem",
+    "Result",
+    # exceptions
+    "PyDSAError",
+    "ProblemNotFoundError",
+    "AmbiguousQueryError",
+    "InvalidInputError",
+    "SolverError",
+]
+
+
+# ── Core API ──────────────────────────────────────────────────────────────────
+
+def solve(query: str | int, /, *args: Any, **kwargs: Any) -> Result:
+    """
+    Find and execute the best-matching algorithm for the given query.
+
+    Parameters
+    ----------
+    query : str | int
+        A natural-language description, problem name, alias, tag, slug,
+        or integer LeetCode problem id.
+    *args :
+        Input arguments forwarded directly to the solver function.
+    **kwargs :
+        Keyword arguments forwarded directly to the solver function.
+
+    Returns
+    -------
+    Result
+        Structured output with .answer, .time_complexity, .space_complexity,
+        .difficulty, .tags, .description.
+
+    Raises
+    ------
+    ProblemNotFoundError
+        Query matched no known problem.
+    AmbiguousQueryError
+        Query matched multiple problems at similar confidence.
+    InvalidInputError
+        Input arguments are wrong for the matched solver.
+    SolverError
+        The solver raised an unexpected internal exception.
+
+    Examples
+    --------
+    >>> solve("two sum", [2, 7, 11, 15], 9)
+    Result(problem='Two Sum', answer=[0, 1], ...)
+
+    >>> solve(11, [1,8,6,2,5,4,8,3,7])
+    Result(problem='Container With Most Water', answer=49, ...)
+
+    >>> solve("rearrange array by sign", [3, 1, -2, -5, 2, -4])
+    Result(problem='Rearrange Array Elements by Sign', answer=[3,-2,1,-5,2,-4], ...)
+    """
+    trace_flag = kwargs.pop("trace", False)
+    problem = find(query)
+    result  = execute(problem, args, kwargs, trace=trace_flag)
+    result.match_score = 1.0  # exact or high-confidence fuzzy
+    return result
+
+
+def search(query: str, limit: int = 10) -> list[Problem]:
+    """
+    Return up to `limit` problems matching the query, sorted by relevance.
+
+    Unlike ``solve()``, this never raises — returns [] if nothing matches.
+    Useful for autocomplete, exploration, and building UIs on top of pydsa.
+
+    Examples
+    --------
+    >>> results = search("sliding window")
+    >>> for p in results:
+    ...     print(p.id, p.name, p.difficulty)
+    """
+    return _search(query, limit=limit)
+
+
+def info(query: str | int) -> Problem:
+    """
+    Return the Problem metadata for a query without executing the solver.
+
+    Examples
+    --------
+    >>> p = info("two sum")
+    >>> print(p.time_complexity)  # O(n)
+    >>> print(p.tags)             # ['hash_map', 'array']
+    """
+    return find(query)
+
+
+def list_problems(
+    category:   str | None = None,
+    difficulty: str | None = None,
+    tag:        str | None = None,
+) -> list[Problem]:
+    """
+    List all registered problems with optional filters.
+
+    Parameters
+    ----------
+    category :   filter by category  (e.g. "arrays", "dp")
+    difficulty : filter by difficulty ("easy", "medium", "hard")
+    tag :        filter by tag        (e.g. "two_pointer", "bfs")
+
+    Examples
+    --------
+    >>> easy_dp = list_problems(category="dp", difficulty="easy")
+    """
+    problems = _registry.all_problems()
+    if category:
+        problems = [p for p in problems if p.category == category.lower()]
+    if difficulty:
+        problems = [p for p in problems if p.difficulty == difficulty.lower()]
+    if tag:
+        t = tag.lower()
+        problems = [p for p in problems if t in p.tags]
+    return problems
+
+
+def stats() -> dict:
+    """
+    Return a summary of the registry.
+
+    Examples
+    --------
+    >>> import pydsa
+    >>> pydsa.stats()
+    {'total': 3944, 'categories': {'arrays': 812, ...}, 'difficulty': {...}}
+    """
+    return _registry.stats()

pydsa/__main__.py

@@ -0,0 +1,218 @@
+import argparse
+import sys
+import ast
+import inspect
+from rich.console import Console
+from rich.syntax import Syntax
+from rich.table import Table
+from rich.panel import Panel
+from rich import box
+
+# Import the core engine you built
+from pydsa import solve as _solve, search as _search, info as _info
+from pydsa.core.exceptions import PyDSAError
+
+def copy_to_clipboard(text: str):
+    """Safely attempts to copy text to the system clipboard."""
+    try:
+        import pyperclip
+        pyperclip.copy(text)
+        console.print("[bold green]✓ Source code copied to clipboard![/bold green]\n")
+    except ImportError:
+        console.print("[yellow]💡 Tip: Run 'pip install pyperclip' to enable the --copy flag.[/yellow]\n")
+    except Exception as e:
+        console.print(f"[red]Failed to copy to clipboard: {e}[/red]\n")
+
+# Initialize the Rich console for UI rendering
+console = Console()
+
+def get_difficulty_color(diff: str) -> str:
+    """Helper to color-code LeetCode difficulties."""
+    d = diff.lower()
+    if d == "easy": return "[bold green]Easy[/bold green]"
+    if d == "medium": return "[bold yellow]Medium[/bold yellow]"
+    if d == "hard": return "[bold red]Hard[/bold red]"
+    return diff
+
+def parse_cli_args(cli_args: list[str]) -> list:
+    """Safely converts string inputs like '[1,2,3]' into actual Python lists."""
+    parsed = []
+    for arg in cli_args:
+        try:
+            parsed.append(ast.literal_eval(arg))
+        except (ValueError, SyntaxError):
+            parsed.append(arg)  # Keep as string if it's not a list/dict/number
+    return parsed
+
+def run_solve(args):
+    parsed_inputs = parse_cli_args(args.inputs)
+    
+    # --- NEW LOGIC: Bypass execution if no inputs are provided ---
+    if not parsed_inputs:
+        if not args.show_code and not args.copy:
+            console.print("\n[bold red]Error:[/bold red] You must provide inputs to execute the algorithm, OR use [yellow]--show-code[/yellow] to view the source code.\n")
+            return
+            
+        # Use the AI search to route the query to the best problem without executing it
+        with console.status(f"[bold cyan]Routing query '{args.query}'...", spinner="dots"):
+            problems = _search(args.query, limit=1)
+            
+        if not problems:
+            console.print(f"\n[bold red]X[/bold red] No problems found matching '[yellow]{args.query}[/yellow]'.\n")
+            return
+            
+        problem_obj = problems[0]
+        
+        # Print Header & Code, then exit early!
+        console.print()
+        console.print(Panel(f"[bold white]{problem_obj.name}[/bold white]  [dim]({problem_obj.category})[/dim]", expand=False, border_style="cyan"))
+        
+        source_code = inspect.getsource(problem_obj.solver)
+
+        #COPY THE SOURCE CODE TO CLIPBOARD IF THE FLAG IS SET
+        if args.copy:
+            copy_to_clipboard(source_code)
+            if not args.show_code:
+                return 
+        console.print()
+        console.print(Panel(f"[bold white]{problem_obj.name}[/bold white]  [dim]({problem_obj.category})[/dim]", expand=False, border_style="cyan"))
+
+        syntax = Syntax(source_code, "python", theme="monokai", line_numbers=True)
+        
+        console.print()
+        console.print(Panel(syntax, title=f"[bold green]Source Code: {problem_obj.name}[/bold green]", border_style="green", expand=False))
+        console.print()
+        return
+    # --- END NEW LOGIC ---
+    
+    # The loading spinner! (Original execution logic resumes here)
+    with console.status(f"[bold cyan]Routing query '{args.query}' to the AI Brain...", spinner="dots"):
+        result = _solve(args.query, *parsed_inputs, trace=args.trace)
+
+    # 1. The Header Panel
+    console.print()
+    console.print(Panel(
+        f"[bold white]{result.problem}[/bold white]  [dim]({result.category})[/dim]", 
+        expand=False, 
+        border_style="cyan"
+    ))
+
+    # 2. The Complexity Table
+    table = Table(box=box.SIMPLE, show_header=False)
+    table.add_column("Metric", style="bold dim")
+    table.add_column("Value")
+    table.add_row("Difficulty", get_difficulty_color(result.difficulty))
+    table.add_row("Time Complexity", f"[magenta]{result.time_complexity}[/magenta]")
+    table.add_row("Space Complexity", f"[blue]{result.space_complexity}[/blue]")
+    console.print(table)
+
+    # 3. The Output Answer
+    console.print("[bold yellow]Result:[/bold yellow]")
+    console.print(result.answer)
+    
+    # 4. (Optional) The Source Code Viewer
+    if args.show_code or args.copy:
+        # 1. Fetch the full Problem object using the exact name returned by the result
+        problem_obj = _info(result.problem)
+        
+        # 2. Extract the raw source code of the function in memory
+        source_code = inspect.getsource(problem_obj.solver)
+
+        # --- ADD COPY LOGIC HERE ---
+        if args.copy:
+            copy_to_clipboard(source_code)
+
+        if args.show_code:
+        # 3. Render it beautifully with syntax highlighting
+            syntax = Syntax(source_code, "python", theme="monokai", line_numbers=True)
+
+            console.print()
+            console.print(Panel(
+                syntax, 
+                title=f"[bold green]Source Code: {result.problem}[/bold green]",
+                border_style="green",
+                expand=False
+            ))
+            console.print()
+        
+    # 5. The Execution Trace
+    if args.trace and result.trace_history:
+        console.print(f"\n[bold magenta]🔍 Algorithm Execution Trace (First {len(result.trace_history)} steps)[/bold magenta]")
+        
+        trace_table = Table(box=box.MINIMAL_DOUBLE_HEAD, show_lines=True)
+        trace_table.add_column("Step", justify="center", style="dim")
+        trace_table.add_column("Line No.", justify="center", style="cyan")
+        trace_table.add_column("Local Variables State", style="green")
+
+        for step, (line_no, variables) in enumerate(result.trace_history):
+            # Format the dictionary into a nice string: "i: 0 | target: 9 | map: {}"
+            var_str = "\n".join([f"[bold white]{k}[/bold white]: {v}" for k, v in variables.items()])
+            trace_table.add_row(str(step + 1), str(line_no), var_str)
+
+        console.print(trace_table)
+    console.print()
+
+def run_search(args):
+    with console.status(f"[bold cyan]Searching registry for '{args.query}'...", spinner="dots"):
+        problems = _search(args.query, limit=args.limit)
+
+    if not problems:
+        console.print(f"\n[bold red]X[/bold red] No problems found matching '[yellow]{args.query}[/yellow]'.\n")
+        return
+
+    # Build the Search Results Table
+    table = Table(title=f"Search Results for '{args.query}'", box=box.ROUNDED, border_style="dim")
+    table.add_column("ID", justify="right", style="cyan", no_wrap=True)
+    table.add_column("Problem Name", style="bold white")
+    table.add_column("Difficulty")
+    table.add_column("Tags", style="dim")
+
+    for p in problems:
+        tags = ", ".join(p.tags[:3]) + ("..." if len(p.tags) > 3 else "")
+        table.add_row(str(p.id), p.name, get_difficulty_color(p.difficulty), tags)
+
+    console.print()
+    console.print(table)
+    console.print()
+
+def main():
+    parser = argparse.ArgumentParser(prog="pydsa", description="A semantic DSA execution engine.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # CLI Command: solve
+    solve_parser = subparsers.add_parser("solve", help="Solve a problem by description or ID")
+    solve_parser.add_argument("query", help="Natural language description or problem ID")
+    solve_parser.add_argument("inputs", nargs="*", help="The inputs to pass to the algorithm")
+    solve_parser.add_argument("--show-code", action="store_true", help="Display the Python source code of the solver")
+    solve_parser.add_argument("--copy", action="store_true", help="Copy the source code directly to your clipboard")
+    solve_parser.add_argument("--trace", action="store_true", help="Visualize variable state step-by-step")
+    
+    # CLI Command: search
+    search_parser = subparsers.add_parser("search", help="Browse the algorithm registry")
+    search_parser.add_argument("query", help="Topic, tag, or keyword")
+    search_parser.add_argument("--limit", type=int, default=10, help="Max results to show")
+
+    # CLI Command: serve
+    serve_parser = subparsers.add_parser("serve", help="Start the FastAPI REST server")
+    serve_parser.add_argument("--port", type=int, default=8000, help="Port to run the server on")
+
+
+    args = parser.parse_args()
+
+    try:
+        if args.command == "solve":
+            run_solve(args)
+        elif args.command == "search":
+            run_search(args)
+        elif args.command == "serve":
+            # Start the web server!
+            import uvicorn
+            console.print(f"[bold green]Starting PyDSA API Server on http://127.0.0.1:{args.port}[/bold green]")
+            uvicorn.run("pydsa.api.server:app", host="127.0.0.1", port=args.port, reload=False)
+
+    except PyDSAError as e:
+        console.print(f"\n[bold red]Error:[/bold red] {e}\n")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

pydsa/algorithms/arrays/1_bit_and_2_bit_characters.py

@@ -0,0 +1,42 @@
+METADATA = {
+    "id": 717,
+    "name": "1-bit and 2-bit Characters",
+    "slug": "1_bit_and_2_bit_characters",
+    "category": "Algorithms",
+    "aliases": ["One Bit and Two Bit Characters"],
+    "tags": ["array", "greedy"],
+    "difficulty": "easy",
+    "time_complexity": "O(n)",
+    "space_complexity": "O(1)",
+    "description": "Determine whether the final character in a bit sequence is a 1-bit character.",
+}
+
+
+def solve(bits: list[int]) -> bool:
+    """Determine if the last character in the bit sequence is a 1-bit character.
+
+    Args:
+        bits: A list of integers (0 or 1) representing the encoded characters.
+               The sequence always ends with a 0.
+
+    Returns:
+        True if the last character is a 1-bit character, False otherwise.
+
+    Examples:
+        >>> solve([1, 0, 0])
+        True
+        >>> solve([1, 1, 1, 0])
+        False
+    """
+    index: int = 0
+    last_position: int = len(bits) - 1
+
+    # Walk through the array, skipping 1 step for '0' and 2 steps for '1'
+    while index < last_position:
+        if bits[index] == 0:
+            index += 1  # 1-bit character
+        else:
+            index += 2  # 2-bit character
+
+    # If we land exactly on the last element, it must be a 1-bit character
+    return index == last_position

pydsa/algorithms/arrays/4sum_ii.py

@@ -0,0 +1,55 @@
+METADATA = {
+    "id": 454,
+    "name": "4Sum II",
+    "slug": "4sum-ii",
+    "category": "Hash Table",
+    "aliases": [],
+    "tags": ["hash table", "array"],
+    "difficulty": "medium",
+    "time_complexity": "O(n^2)",
+    "space_complexity": "O(n^2)",
+    "description": "Given four integer arrays nums1, nums2, nums3, and nums4, return the number of tuples (i, j, k, l) such that nums1[i] + nums2[j] + nums3[k] + nums4[l] == 0.",
+}
+
+def solve(nums1: list[int], nums2: list[int], nums3: list[int], nums4: list[int]) -> int:
+    """
+    Calculates the number of tuples (i, j, k, l) such that the sum of elements
+    from the four arrays equals zero.
+
+    Args:
+        nums1: First list of integers.
+        nums2: Second list of integers.
+        nums3: Third list of integers.
+        nums4: Fourth list of integers.
+
+    Returns:
+        The total count of tuples that sum to zero.
+
+    Examples:
+        >>> solve([1, 2], [-2, -1], [-1, 2], [0, 2])
+        2
+        >>> solve([0, 1, 2], [-1, -2, -3], [1, 2, 3], [-1, -2, -3])
+        0
+    """
+    # Map to store the frequency of sums from the first two arrays
+    # Key: sum (nums1[i] + nums2[j]), Value: count of occurrences
+    sum_counts: dict[int, int] = {}
+
+    # Step 1: Populate the hash map with all possible sums of pairs from nums1 and nums2
+    for val1 in nums1:
+        for val2 in nums2:
+            current_sum = val1 + val2
+            sum_counts[current_sum] = sum_counts.get(current_sum, 0) + 1
+
+    total_tuples = 0
+
+    # Step 2: Iterate through all possible sums of pairs from nums3 and nums4
+    # If the negative of the current sum exists in our map, it means 
+    # (val1 + val2) + (val3 + val4) == 0
+    for val3 in nums3:
+        for val4 in nums4:
+            target = -(val3 + val4)
+            if target in sum_counts:
+                total_tuples += sum_counts[target]
+
+    return total_tuples

pydsa/algorithms/arrays/absolute_difference_between_maximum_and_minimum_k_elements.py

@@ -0,0 +1,56 @@
+METADATA = {
+    "id": 3774,
+    "name": "Absolute Difference Between Maximum and Minimum K Elements",
+    "slug": "absolute-difference-between-maximum-and-minimum-k-elements",
+    "category": "Array",
+    "aliases": [],
+    "tags": ["sorting", "sliding_window"],
+    "difficulty": "easy",
+    "time_complexity": "O(n log n)",
+    "space_complexity": "O(1)",
+    "description": "Find the minimum absolute difference between the maximum and minimum elements in any subarray of size k after sorting.",
+}
+
+def solve(nums: list[int], k: int) -> int:
+    """
+    Finds the minimum absolute difference between the maximum and minimum 
+    elements in any subset of size k.
+
+    The problem asks for the minimum difference between the max and min of 
+    k elements. To minimize this difference, we should pick k elements 
+    that are closest to each other in value. Sorting the array allows us 
+    to consider only contiguous windows of size k.
+
+    Args:
+        nums: A list of integers.
+        k: The number of elements to select.
+
+    Returns:
+        The minimum absolute difference between the maximum and minimum 
+        elements among any k elements.
+
+    Examples:
+        >>> solve([10, 1, 5, 20, 15], 3)
+        5
+        >>> solve([1, 2, 3, 4], 2)
+        1
+    """
+    n = len(nums)
+    if k <= 1:
+        return 0
+
+    # Sort the array to bring elements with similar values close to each other
+    nums.sort()
+
+    # Initialize min_diff with a very large value
+    min_diff = float('inf')
+
+    # Use a sliding window of size k. 
+    # In a sorted array, for any window [i, i + k - 1], 
+    # the minimum is nums[i] and the maximum is nums[i + k - 1].
+    for i in range(n - k + 1):
+        current_diff = nums[i + k - 1] - nums[i]
+        if current_diff < min_diff:
+            min_diff = current_diff
+
+    return int(min_diff)

pydsa/algorithms/arrays/accepted_candidates_from_the_interviews.py

@@ -0,0 +1,52 @@
+METADATA = {
+    "id": 2041,
+    "name": "Accepted Candidates From the Interviews",
+    "slug": "accepted_candidates_from_the_interviews",
+    "category": "array",
+    "aliases": [],
+    "tags": ["array", "prefix_sum"],
+    "difficulty": "easy",
+    "time_complexity": "O(n)",
+    "space_complexity": "O(1)",
+    "description": "Count candidates whose acceptance ratio is strictly greater than all previous candidates.",
+}
+
+
+def solve(accepted: list[int], interviews: list[int]) -> int:
+    """Count the number of candidates whose acceptance ratio is strictly greater than any
+    candidate before them.
+
+    Args:
+        accepted: List of integers where accepted[i] is the number of accepted offers for
+            candidate i.
+        interviews: List of integers where interviews[i] is the total number of interviews
+            conducted for candidate i. Both lists have the same length.
+
+    Returns:
+        The count of candidates whose accepted[i] / interviews[i] ratio is strictly larger
+        than the maximum ratio observed among all previous candidates.
+
+    Examples:
+        >>> solve([2, 1, 3, 4], [2, 2, 4, 5])
+        3
+        >>> solve([1, 2, 3], [1, 2, 3])
+        1
+    """
+    if not accepted or not interviews or len(accepted) != len(interviews):
+        return 0
+
+    count_of_good_candidates = 0
+    max_accepted = 0
+    max_interviews = 1  # avoid division by zero; ratio = 0 initially
+
+    for idx in range(len(accepted)):
+        current_accepted = accepted[idx]
+        current_interviews = interviews[idx]
+
+        # Compare fractions without floating point: a/b > c/d  <=> a*d > c*b
+        if current_accepted * max_interviews > max_accepted * current_interviews:
+            count_of_good_candidates += 1
+            max_accepted = current_accepted
+            max_interviews = current_interviews
+
+    return count_of_good_candidates

pydsa/algorithms/arrays/account_balance.py

@@ -0,0 +1,39 @@
+METADATA = {
+    "id": 2066,
+    "name": "Account Balance",
+    "slug": "account-balance",
+    "category": "Simulation",
+    "aliases": [],
+    "tags": ["simulation", "array"],
+    "difficulty": "easy",
+    "time_complexity": "O(n)",
+    "space_complexity": "O(1)",
+    "description": "Calculate the final account balance by summing all transaction amounts in a list.",
+}
+
+def solve(transactions: list[int]) -> int:
+    """
+    Calculates the final account balance after a series of transactions.
+
+    Args:
+        transactions: A list of integers representing transaction amounts. 
+                      Positive values are deposits, negative values are withdrawals.
+
+    Returns:
+        The final balance after all transactions have been processed.
+
+    Examples:
+        >>> solve([10, -5, 20, -10])
+        15
+        >>> solve([-5, -5, -5])
+        -15
+        >>> solve([])
+        0
+    """
+    current_balance = 0
+    
+    # Iterate through each transaction and update the running total
+    for amount in transactions:
+        current_balance += amount
+        
+    return current_balance