.. index:: single: metagol
.. _metagol/0:

.. rst-class:: right

**object**

``metagol``
===========

Inductive logic programming (ILP) system based on meta-interpretive learning.

| **Availability:** 
|    ``logtalk_load(metagol(loader))``

| **Author:** Metagol authors; adapted to Logtalk by Paulo Moura.
| **Version:** 0:25:0
| **Date:** 2026-08-10

| **Copyright:** Copyright 2016 Metagol authors; Copyright 2018-2024 Paulo Moura
| **License:** BSD-3-Clause

| **Compilation flags:**
|    ``static, context_switching_calls``


| **Implements:**
|    ``public`` :ref:`expanding <expanding/0>`
| **Provides:**
|    :ref:`logtalk::message_tokens//2 <logtalk/0::message_tokens//2>`
|    :ref:`logtalk::message_prefix_stream/4 <logtalk/0::message_prefix_stream/4>`
| **Uses:**
|    :ref:`coroutining <coroutining/0>`
|    :ref:`integer <integer/0>`
|    :ref:`list <list/0>`
|    :ref:`logtalk <logtalk/0>`
|    :ref:`meta <meta/0>`
|    :ref:`timeout <timeout/0>`

| **Remarks:**
|    (none)

| **Inherited public predicates:**
|     :ref:`expanding/0::goal_expansion/2`  :ref:`expanding/0::term_expansion/2`  

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: learn/3
.. _metagol/0::learn/3:

``learn/3``
^^^^^^^^^^^

Learns from a set of positive examples and a set of negative examples and returns the learned program.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``learn(PositiveExamples,NegativeExamples,Program)``
| **Mode and number of proofs:**
|    ``learn(@list(example),@list(example),-list(term))`` - ``zero_or_more``


------------

.. index:: learn/2
.. _metagol/0::learn/2:

``learn/2``
^^^^^^^^^^^

Learns from a set of positive examples and a set of negative examples and pretty prints the learned program.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``learn(PositiveExamples,NegativeExamples)``
| **Mode and number of proofs:**
|    ``learn(@list(example),@list(example))`` - ``zero_or_more``


------------

.. index:: learn_seq/2
.. _metagol/0::learn_seq/2:

``learn_seq/2``
^^^^^^^^^^^^^^^

Learns from a sequence of examples represented as a list of PositiveExamples/NegativeExamples elements and returns the learned program.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``learn_seq(Examples,Program)``
| **Mode and number of proofs:**
|    ``learn_seq(@list(example),-list(clause))`` - ``zero_or_one``


------------

.. index:: learn_with_timeout/4
.. _metagol/0::learn_with_timeout/4:

``learn_with_timeout/4``
^^^^^^^^^^^^^^^^^^^^^^^^

Learns from a set of positive examples and a set of negative examples and returns the learned program constrained by the given timeout or its default value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``learn_with_timeout(PositiveExamples,NegativeExamples,Program,Timeout)``
| **Mode and number of proofs:**
|    ``learn_with_timeout(@list(example),@list(example),-list(term),+number)`` - ``zero_or_one_or_error``
|    ``learn_with_timeout(@list(example),@list(example),-list(term),-number)`` - ``zero_or_one_or_error``

| **Exceptions:**
|    Learning does not complete in the allowed time:
|        ``timeout(learn(PositiveExamples,NegativeExamples,Program))``


------------

.. index:: program_to_clauses/2
.. _metagol/0::program_to_clauses/2:

``program_to_clauses/2``
^^^^^^^^^^^^^^^^^^^^^^^^

Converts a learned program into a list of clauses.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``program_to_clauses(Program,Clauses)``
| **Mode and number of proofs:**
|    ``program_to_clauses(@list(term),-list(clause))`` - ``one``


------------

.. index:: pprint/1
.. _metagol/0::pprint/1:

``pprint/1``
^^^^^^^^^^^^

Pretty prints a learned program.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pprint(Program)``
| **Mode and number of proofs:**
|    ``pprint(@list(term))`` - ``one``


------------

.. index:: metarule/6
.. _metagol/0::metarule/6:

``metarule/6``
^^^^^^^^^^^^^^

Compiled metarule, generated from a user-defined metarule/3 or metarule/4 clause, relating a name, its substitutions, a head atom, a body, a recursion flag, and the current call path.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``metarule(Name,Subs,Head,Body,Recursive,Path)``
| **Mode and number of proofs:**
|    ``metarule(?atom,?list,?callable,?list,?atom,?list)`` - ``zero_or_more``


------------

.. index:: head_pred/1
.. _metagol/0::head_pred/1:

``head_pred/1``
^^^^^^^^^^^^^^^

Declares a predicate indicator that can be used in the head of a learned clause.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``head_pred(PredicateIndicator)``
| **Mode and number of proofs:**
|    ``head_pred(?predicate_indicator)`` - ``zero_or_more``


------------

.. index:: ibk/3
.. _metagol/0::ibk/3:

``ibk/3``
^^^^^^^^^

Interpreted background knowledge clause, generated from a user-defined ibk/2 fact or rule, relating a head atom (as a list) to a body (as a list of atoms) and the current call path.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``ibk(Head,Body,Path)``
| **Mode and number of proofs:**
|    ``ibk(?list,?list,?list)`` - ``zero_or_more``


------------

.. index:: func_test/3
.. _metagol/0::func_test/3:

``func_test/3``
^^^^^^^^^^^^^^^

Relates an atom to a test atom and a condition used to check that the learned program is functional.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``func_test(Atom,TestAtom,Condition)``
| **Mode and number of proofs:**
|    ``func_test(@callable,-callable,-callable)`` - ``zero_or_more``


------------

.. index:: body_pred/1
.. _metagol/0::body_pred/1:

``body_pred/1``
^^^^^^^^^^^^^^^

Declares a predicate indicator that can be used in the body of a learned clause.

| **Compilation flags:**
|    ``dynamic``

| **Template:**
|    ``body_pred(PredicateIndicator)``
| **Mode and number of proofs:**
|    ``body_pred(?predicate_indicator)`` - ``zero_or_more``


------------

.. index:: functional/0
.. _metagol/0::functional/0:

``functional/0``
^^^^^^^^^^^^^^^^

True when the learned program is required to be functional (deterministic).

| **Compilation flags:**
|    ``dynamic``

| **Mode and number of proofs:**
|    ``functional`` - ``zero_or_one``


------------

.. index:: min_clauses/1
.. _metagol/0::min_clauses/1:

``min_clauses/1``
^^^^^^^^^^^^^^^^^

Minimum number of clauses to try when searching for a learned program.

| **Compilation flags:**
|    ``dynamic``

| **Template:**
|    ``min_clauses(MinClauses)``
| **Mode and number of proofs:**
|    ``min_clauses(?integer)`` - ``zero_or_one``


------------

.. index:: max_clauses/1
.. _metagol/0::max_clauses/1:

``max_clauses/1``
^^^^^^^^^^^^^^^^^

Maximum number of clauses to try when searching for a learned program.

| **Compilation flags:**
|    ``dynamic``

| **Template:**
|    ``max_clauses(MaxClauses)``
| **Mode and number of proofs:**
|    ``max_clauses(?integer)`` - ``zero_or_one``


------------

.. index:: max_inv_preds/1
.. _metagol/0::max_inv_preds/1:

``max_inv_preds/1``
^^^^^^^^^^^^^^^^^^^

Maximum number of invented predicate symbols allowed per learning task.

| **Compilation flags:**
|    ``dynamic``

| **Template:**
|    ``max_inv_preds(MaxInventedPredicates)``
| **Mode and number of proofs:**
|    ``max_inv_preds(?integer)`` - ``zero_or_one``


------------

.. index:: metarule_next_id/1
.. _metagol/0::metarule_next_id/1:

``metarule_next_id/1``
^^^^^^^^^^^^^^^^^^^^^^

Next identifier to use when generating a name for an anonymous metarule.

| **Compilation flags:**
|    ``dynamic``

| **Template:**
|    ``metarule_next_id(Id)``
| **Mode and number of proofs:**
|    ``metarule_next_id(?integer)`` - ``zero_or_one``


------------

.. index:: timeout/1
.. _metagol/0::timeout/1:

``timeout/1``
^^^^^^^^^^^^^

Default timeout, in seconds, used when learning a program.

| **Compilation flags:**
|    ``dynamic``

| **Template:**
|    ``timeout(Timeout)``
| **Mode and number of proofs:**
|    ``timeout(?number)`` - ``zero_or_one``


------------

Protected predicates
--------------------

.. index:: pprint_clause/1
.. _metagol/0::pprint_clause/1:

``pprint_clause/1``
^^^^^^^^^^^^^^^^^^^

Pretty prints a single learned clause. Can be redefined to customize the printing of learned clauses.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pprint_clause(Clause)``
| **Mode and number of proofs:**
|    ``pprint_clause(@clause)`` - ``one``


------------

.. index:: compiled_pred_call/2
.. _metagol/0::compiled_pred_call/2:

``compiled_pred_call/2``
^^^^^^^^^^^^^^^^^^^^^^^^

Asserted clause used to call a compiled (pre-existing) predicate given its name and list of arguments.

| **Compilation flags:**
|    ``dynamic``

| **Template:**
|    ``compiled_pred_call(Predicate,Arguments)``
| **Mode and number of proofs:**
|    ``compiled_pred_call(?atom,?list)`` - ``zero_or_more``


------------

.. index:: body_pred_call/2
.. _metagol/0::body_pred_call/2:

``body_pred_call/2``
^^^^^^^^^^^^^^^^^^^^

Asserted clause used to call a background knowledge predicate given its name and list of arguments.

| **Compilation flags:**
|    ``dynamic``

| **Template:**
|    ``body_pred_call(Predicate,Arguments)``
| **Mode and number of proofs:**
|    ``body_pred_call(?atom,?list)`` - ``zero_or_more``


------------

.. index:: type/3
.. _metagol/0::type/3:

``type/3``
^^^^^^^^^^

Asserted fact classifying a predicate, given by its name and arity, by its role (head_pred, body_pred, ibk_head_pred, or compiled_pred).

| **Compilation flags:**
|    ``dynamic``

| **Template:**
|    ``type(Name,Arity,Type)``
| **Mode and number of proofs:**
|    ``type(?atom,?integer,?atom)`` - ``zero_or_more``


------------

Private predicates
------------------

(no local declarations; see entity ancestors if any)

Operators
---------

(none)

