luplo.core.links
================

.. py:module:: luplo.core.links

.. autoapi-nested-parse::

   CRUD operations for the links table.

   Links are typed, weighted edges between items — e.g. ``excludes``,
   ``synergizes_with``, ``interacts_with``.  The ``link_type`` is free-form
   text (not an enum) so new relationship types can appear as systems grow.



Functions
---------

.. autoapisummary::

   luplo.core.links.create_link
   luplo.core.links.get_links
   luplo.core.links.delete_link


Module Contents
---------------

.. py:function:: create_link(conn: psycopg.AsyncConnection[Any], *, from_item_id: str, to_item_id: str, link_type: str, strength: int = 5, note: str | None = None, actor_id: str | None = None) -> luplo.core.models.Link
   :async:


   Create a typed edge between two items.

   :param conn: Async psycopg connection.
   :param from_item_id: Source item.
   :param to_item_id: Target item.
   :param link_type: Relationship type (e.g. ``"excludes"``).
   :param strength: Weight 1-10, default 5.
   :param note: Optional annotation.
   :param actor_id: Who created this link.

   :returns: The newly created ``Link``.

   :raises psycopg.errors.UniqueViolation: If the exact
       ``(from_item_id, to_item_id, link_type)`` triple already exists.


.. py:function:: get_links(conn: psycopg.AsyncConnection[Any], item_id: str, *, direction: str = 'from', link_type: str | None = None) -> list[luplo.core.models.Link]
   :async:


   Query links connected to an item.

   :param conn: Async psycopg connection.
   :param item_id: The item to query links for.
   :param direction: ``"from"`` (outgoing), ``"to"`` (incoming),
                     or ``"both"``.
   :param link_type: Optional filter by relationship type.

   :returns: List of matching ``Link`` objects ordered by ``created_at DESC``.


.. py:function:: delete_link(conn: psycopg.AsyncConnection[Any], from_item_id: str, to_item_id: str, link_type: str) -> bool
   :async:


   Delete a link by its composite primary key.

   :returns: ``True`` if the link existed and was deleted, ``False`` otherwise.