💘 Cupidin API: Stable Marriage as a Service

Tired of love being a chaotic mess? Cupidin is the ultimate backend that uses heavy math and OR-Tools to solve the Stable Marriage Problem. Because if your love life isn't stable, at least your algorithm should be.

Built with FastAPI so your breakups are asynchronous and lightning-fast. 🚀

---

🧠 How it works

Cupidin doesn't believe in "fate." It believes in CP-SAT (Constraint Programming).

1. The Input: We receive a list of people and their preferences (from "Supreme Crush" to "Well, better than nothing").
2. The Engine: We run an optimization model that guarantees no one will cheat on their partner with someone who also prefers to be with them (Mathematical Stability).
3. The Cold Truth: If you end up alone, it’s not our fault—your SolveOptions were probably just too demanding.

---

🛠️ Tech Stack

• FastAPI: A server faster than your last ex ghosting you.
• Google OR-Tools: Because love is just a constraint satisfaction problem.
• Pydantic: Validating that your suitors at least have a valid ID.

---

📡 Endpoints

POST /validate 🧐

Before you dive into the dating pool, we validate your data:

• Duplicate IDs? (You can't be on two dates at once, even if you try).
• Missing preferences? (Interest must be mutual, or at least exist).
• Gender Balance? (No third-wheeling allowed here; we need equal numbers for a perfect match).

POST /solve 💍

Where the magic happens. Send the instance and options, and we return the Perfect Matching.

• Proposer: Who makes the first move? Men or Women? (Spoiler: In this algorithm, the proposer always gets the better deal).
• WomenMaxRank: For those with high standards. If you aren't in their Top K, don't even bother.

---

🚀 Local Installation

If you want to run Cupidin on your machine (because local love is always better):

1. Clone the repo:

   git clone [https://github.com/your-username/cupidin-api](https://github.com/your-username/cupidin-api)

2. Install dependencies (you need Python, not Docker... this time!):

   pip install fastapi uvicorn ortools pydantic

3. Ignite the flame:

   uvicorn main:app --reload

---

⚠️ Disclaimer

Cupidin guarantees mathematical stability, not emotional happiness. If your stable partner according to the algorithm has a rank of 10 (your very last choice), please take your complaints to: 📧 daniellavargas@ieee.org