{"id":37074394,"url":"https://github.com/alex-87/qaekwy-python","last_synced_at":"2026-01-14T08:46:13.053Z","repository":{"id":190774204,"uuid":"683347498","full_name":"alex-87/qaekwy-python","owner":"alex-87","description":"A modern, open-source Python framework for declarative constraint programming and combinatorial optimization.","archived":false,"fork":false,"pushed_at":"2026-01-10T18:32:27.000Z","size":202,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-11T05:14:07.686Z","etag":null,"topics":["branch-and-bound","client-library","constraint-programming","constraint-satisfaction-and-optimization","constraint-satisfaction-problem","csp","csp-solver","decision-making","deep-first-search","modeling","modelling","modelling-framework","operational-research","optimization","python","search-engine-optimization","solver","solver-algorithm"],"latest_commit_sha":null,"homepage":"https://docs.qaekwy.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"eupl-1.2","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alex-87.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-08-26T09:21:20.000Z","updated_at":"2026-01-10T18:23:57.000Z","dependencies_parsed_at":"2024-01-18T00:29:45.881Z","dependency_job_id":"bf784833-7554-4889-b726-5fa89f1a17f7","html_url":"https://github.com/alex-87/qaekwy-python","commit_stats":{"total_commits":2,"total_committers":1,"mean_commits":2.0,"dds":0.0,"last_synced_commit":"00000dfa9eeb9bb58fa9e1452ce9c5bd8ca804c0"},"previous_names":["alex-87/qaekwy-python"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/alex-87/qaekwy-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex-87%2Fqaekwy-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex-87%2Fqaekwy-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex-87%2Fqaekwy-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex-87%2Fqaekwy-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alex-87","download_url":"https://codeload.github.com/alex-87/qaekwy-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex-87%2Fqaekwy-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28414693,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:38:59.149Z","status":"ssl_error","status_checked_at":"2026-01-14T08:38:43.588Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["branch-and-bound","client-library","constraint-programming","constraint-satisfaction-and-optimization","constraint-satisfaction-problem","csp","csp-solver","decision-making","deep-first-search","modeling","modelling","modelling-framework","operational-research","optimization","python","search-engine-optimization","solver","solver-algorithm"],"created_at":"2026-01-14T08:46:12.302Z","updated_at":"2026-01-14T08:46:13.045Z","avatar_url":"https://github.com/alex-87.png","language":"Python","readme":"# Qaekwy Python\n\n*A modern, open-source Python framework for declarative constraint programming and combinatorial optimization*.\n\n![GitHub License](https://img.shields.io/github/license/alex-87/qaekwy-python) ![PyPI - Version](https://img.shields.io/pypi/v/qaekwy)\n## Overview\n\nQaekwy is a Python library designed for modeling and solving combinatorial optimization and constraint satisfaction problems.\n\nIt provides a clean, Pythonic interface for defining variables, constraints, and objectives, enabling a natural *define-and-solve* workflow. Qaekwy manages the interaction with the solver engine, allowing users to focus entirely on expressing the structure of their problems.\n\n#### Perfect for\n\n* 🎓 **Learning** — Model real problems in minutes\n* 👩‍🏫 **Teaching** — Demonstrate CSP concepts with no setup\n* 🔬 **Research \u0026 Prototyping** — Explore models, heuristics, and ideas fast\n\n## 📚 Documentation\n\nVisit the [Qaekwy Documentation](https://docs.qaekwy.io/) for guides, teaching resources, and detailed examples.\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Python 3.9+\n- pip\n\n### Installation\n\n```shell\npip install qaekwy\n```\n\n### 🌱 Your First Model\n\n```python\nimport qaekwy as qw\n\nm = qw.Model()\n\nx = m.integer_variable(\"x\", (-10, 10))\ny = m.integer_variable(\"y\", (-10, 10))\nz = m.integer_variable(\"z\", (-10, 10))\n\nm.constraint(x + 2*y + 3*z \u003c= 15)\nm.maximize(x)\n\nm.solve_one(searcher=\"bab\").pretty_print()\n```\n\n*Output*:\n\n```text\n----------------------------------------\nSolution:\n----------------------------------------\nx: 10\ny: 2\nz: -4\n----------------------------------------\n```\n\n\n## Capabilities\n\n* **Declarative Modeling**\nDefine integer, float, and boolean variables, as well as arrays and matrices, to represent problems at a high semantic level.\n* **Expressive Constraints**\nFormulate arithmetic, logical, and conditional constraints using readable and maintainable Python expressions.\n* **Optimization Objectives**\nSpecify minimization and maximization goals to guide the solver toward optimal solutions.\n* **Search Configuration**\nConfigure solver behavior using explicit search strategies such as Depth-First Search and Branch-and-Bound, along with branching heuristics and cutoffs.\n* **Cloud-Native Execution**\nTransparent handling of model serialization and execution on the Qaekwy Cloud Solver instance.\n\n\n## Examples\n\n### 🔢 Constraint Programming -- Sudoku\n\nHere is a complete example solving a [Sudoku](https://en.wikipedia.org/wiki/Sudoku) grid:\n\n\u003e The objective is to fill a 9 × 9 grid with digits so that each column, each row, and each\n\u003e of the nine 3 × 3 subgrids that compose the grid contains all of the digits from 1 to 9.\n\n```python\nimport qaekwy as qw\n\n# Initial Sudoku grid; 0 represents empty cells to be assigned by Qaekwy\nmy_problem = [\n    [0, 7, 0,  0, 0, 0,  6, 9, 0],\n    [0, 0, 0,  6, 1, 0,  0, 0, 0],\n    [0, 9, 2,  0, 0, 0,  0, 5, 0],\n\n    [0, 0, 0,  0, 8, 1,  7, 0, 9],\n    [4, 0, 0,  0, 0, 3,  0, 0, 0],\n    [0, 0, 0,  0, 5, 6,  1, 0, 8],\n\n    [0, 5, 9,  0, 0, 0,  0, 1, 0],\n    [0, 0, 0,  5, 6, 0,  0, 0, 0],\n    [0, 2, 0,  0, 0, 0,  5, 7, 0]\n]\n\n# Instantiate the model\nm = qw.Model()\n\n# Create a 9x9 matrix of integer variables\n# Each variable can take a value between 1 and 9 (inclusive)\ngrid = m.integer_matrix(\"grid\", rows=9, cols=9, domain=(1, 9))\n\nfor i in range(9):\n    # Ensure all variables in row 'i' are unique\n    m.constraint_distinct(grid.row(i))\n    \n    # Ensure all variables in column 'i' are unique\n    m.constraint_distinct(grid.col(i))\n\n# Iterate over 3x3 blocks\nfor i in range(0, 9, 3):\n    for j in range(0, 9, 3):\n        # Extract the 3x3 block and enforce uniqueness\n        m.constraint_distinct(grid.slice(i, j, i + 3, j + 3))\n\nfor i in range(9):\n    for j in range(9):\n        # If the cell is not empty (0 represents empty in our data)\n        if my_problem[i][j] != 0:\n            # Constrain the model variable at [i][j] to equal the input value\n            m.constraint(grid[i][j] == my_problem[i][j])\n\n# Solve the model and retrieve the first valid solution found\ns = m.solve_one()\n\n# Display the result\ns.pretty_print()\n```\n\n*Output*:\n\n```text\n----------------------------------------\nSolution:\n----------------------------------------\ngrid: (9 x 9 matrix)\n    1 7 8 3 2 5 6 9 4\n    5 4 3 6 1 9 8 2 7\n    6 9 2 7 4 8 3 5 1\n    2 6 5 4 8 1 7 3 9\n    4 8 1 9 7 3 2 6 5\n    9 3 7 2 5 6 1 4 8\n    7 5 9 8 3 2 4 1 6\n    3 1 4 5 6 7 9 8 2\n    8 2 6 1 9 4 5 7 3\n----------------------------------------\n```\n\n### 🎒 Optimization -- Knapsack Problem\n\nHere is a complete example solving a basic resource allocation problem ([The Knapsack Problem](https://en.wikipedia.org/wiki/Knapsack_problem)):\n\n\u003e Given a set of items, each with a weight and a value, determine which items to include in the\n\u003e collection so that the total weight is less than or equal to a given limit and the total value\n\u003e is as large as possible.\n\n```python\nimport qaekwy as qw\n\n# 1. Setup the Model\nm = qw.Model()\n\nweights = [2, 3, 4, 5]\nvalues  = [3, 4, 5, 6]\nlimit   = 7\nn_items = len(weights)\n\n# 2. Define Decision Variables (0 = exclude, 1 = include)\nselected = [\n    m.integer_variable(f\"item_{i}\", domain=(0, 1))\n    for i in range(n_items)\n]\n\n# 3. Apply Constraints\n# Total weight must not exceed the limit\ncurrent_weight = sum(weights[i] * selected[i] for i in range(n_items))\nm.constraint(current_weight \u003c= limit)\n\n# 4. Define Objective\n# Maximize total value\ntotal_value = m.integer_variable(\n    name=\"total_value\",\n    expression=sum(values[i] * selected[i] for i in range(n_items)),\n    branch_val=qw.BranchIntegerVal.VAL_MAX # Forces the solver to try higher values first\n)\nm.maximize(total_value)\n\n# 5. Solve\nsolution = m.solve_one(searcher=\"bab\") # Branch-and-Bound\n\nprint(f\"Max Value: {solution.total_value}\")\n# Output: Max Value: 9\n```\n\n## 💡 Core Concepts\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Qaekwy core concept\" src=\"https://qaekwy.io/q1.png\" width=\"50%\"\u003e\n\u003c/p\u003e\n\n### The Model\n\nThe `qw.Model` acts as the container for your variables and constraints. It also manages the interaction with\nthe underlying solver engine.\n\n#### The Variables\n\nHere are examples of variable creation in the model:\n\n```python\n# A single integer between 0 and 100\ncapacity = m.integer_variable(\"capacity\", domain=(0, 100))\n\n# A 9x9 Grid (Matrix) for Sudoku-like problems\ngrid = m.integer_matrix(\"grid\", rows=9, cols=9, domain=(1, 9))\n```\n\n#### The Constraints\n\nConstraints are logical assertions that must be true in any valid solution.\n\n```python\n# Arithmetic\nm.constraint(x * 2 \u003c qw.math.power(y, 2) + 5)\n```\n\n### Modeling Capabilities\n\nQaekwy supports:\n\n* Conditional constraints\n\n```python\nm.constraint_if_then_else(\n    condition=x + y \u003c= 7,\n    then_constraint=z \u003e= 2,\n    else_constraint=z \u003c= 2\n)\n```\n\n* Logical expressions\n\n```python\nm.constraint(\n    (qw.math.absolute(z) == qw.math.power(x-(y+1),2)) | (z \u003e= 4)\n)\n```\n\n* Arrays and Matrices\n\n```python\narr = m.integer_array(\"arr\", 3, (0,100))\nm.constraint(arr[1] \u003c x + 1)\n\nmat = m.integer_matrix(\"mat\", rows=2, cols=3, domain=(0,50))\nm.constraint(sum(mat.col(0)) \u003e arr[2])\n```\n\n*...and more, visit the [Qaekwy Documentation](https://docs.qaekwy.io/)*\n\n\n### Solving \u0026 Execution\n\n- `solve_one()` — find one feasible or optimal solution\n- `solve()` — returns a list of solutions\n- `minimize(...)` / `maximize(...)` — Set one or more objectives on variables\n- Searchers such as DFS, Branch-and-Bound, etc.\n- Cloud-based Solver instance (*please, refer to [Terms \u0026 Conditions](https://docs.qaekwy.io/docs/terms-and-conditions/)*)\n\n\n#### Integration\n\nThe model is then sent to the Qaekwy Cloud Engine through REST API.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Qaekwy Integration\" src=\"https://qaekwy.io/q2.png\" width=\"50%\"\u003e\n\u003c/p\u003e\n\n\n## License\n\n- Released under the [European Union Public Licence 1.2 (EUPL 1.2)](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12).\n- Qaekwy Cloud Instance [Terms \u0026 Conditions](https://docs.qaekwy.io/docs/terms-and-conditions/).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falex-87%2Fqaekwy-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falex-87%2Fqaekwy-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falex-87%2Fqaekwy-python/lists"}