lipas 0.3.0__tar.gz

lipas-0.3.0/.gitignore

@@ -0,0 +1,210 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+lipas/__pycache__/
+examples/__pycache__/
+tests/__pycache__/
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

lipas-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 @MetataoOfficial
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lipas-0.3.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: lipas
+Version: 0.3.0
+Summary: Layered Invariant-Preserving Agent System
+Project-URL: Homepage, https://github.com/lipworld/lipas
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# LIPAS
+
+**An agent framework built on algebra, not architecture.**
+
+> Everything is a Claim. One operation -- ⊕  -- derives the rest.
+>
+> Monotonicity, recording, and convergence are consequences -- not axioms.
+
+---
+
+## What You Actually Write
+
+Most of the algebra stays below the surface. The programming interface you touch daily is `lipas.flow` — a declarative pipeline where you describe **what each step needs** and **what it produces**, and the framework handles execution, failure, retries, and context threading.
+
+```python
+```
+
+That is a complete, runnable agent. There is no state machine, no edge list, no router config.
+
+You write one function per capability, declare its inputs and outputs, and `Pipeline` threads the context through ⊕ for you.
+
+The cognitive load is minimal: each function is a plain Python function whose signature names the context keys it reads, and whose return dict names the keys it writes.
+
+**You never manually route data, catch retry loops, or wire failure handlers — ⊕ absorbs every outcome and the pipeline converges.**
+
+---
+
+## What is LIPAS?
+
+Most agent frameworks give you a box of components — planners, memory stores, tool routers — and ask you to wire them together.
+
+LIPAS starts from a different place: a single algebraic operation.
+
+The practical consequence is that you _**stop writing glue**_ and start writing intent:
+
+- **You declare what the agent wants, not how it gets there.** A policy is a flow, which can be described as a YAML file of priorities and conditions. There is no control flow to wire, no state machine to draw, no edge cases to enumerate.
+- **Failure handling writes itself.** Every outcome — success or failure — is a Claim that merges into belief via ⊕. The agent accumulates experience monotonically: it cannot forget a lesson, and it provably stops repeating the same mistake.
+- **Complexity stays flat.** Adding a new capability is one handler function and one commitment entry. The algebra composes them; you don't have to reason about interactions.
+- **The LLM is just another claim source.** Its output is unreliable — fine. ⊕ treats an LLM response exactly like a sensor reading or a user input: a Claim with a priority. The algebra absorbs hallucinations the same way it absorbs any other low-confidence signal.
+
+---
+
+**⊕ (claim merge)** is a join on a field-indexed product semilattice.
+
+```
+You supply: deliberation (strategy)
+⊕ supplies: everything else
+```
+
+---
+
+From this one operation, the entire agent architecture is *derived*, not designed:
+
+- **Belief** is the cumulative fold of epistemic claims under ⊕. Monotonicity is a theorem, not an assumption.
+- **Commitment** is a conative claim with a priority field. Arbitration falls out of the semilattice order.
+- **Effect** is an action that, when executed, produces new claims — closing the perception-action loop.
+
+- **Learning** is what happens when effectual claims (failure records, outcome observations) are folded back into belief via ⊕. Every failed effect produces a (commitment_kind, OutcomeTag) record. When failures for a given kind exceed the caution threshold, the agent expects that failure and stops committing to it. This is not hard-coded retry logic — it is a threshold on a monotone counter that ⊕ maintains. Convergence toward competence is a consequence of belief monotonicity. Other frameworks either lack adaptation entirely or bolt on a learning module long after the fact. In LIPAS, learning is not a pluggable component, not a separate pipeline stage, not an external memory store — it is a mathematical consequence of Claim merging. You cannot "turn off" learning any more than you can remove addition from arithmetic; it is belief accumulation.
+- **Adaptation** is gradient: the agent progresses through adaptation levels (REACTIVE → CAUTIOUS → STRATEGIC → REFLECTIVE) as belief accumulates. A fresh agent is REACTIVE; after enough observations it becomes CAUTIOUS; with learned expectations it reaches STRATEGIC; with sufficient history for meta-reasoning it becomes REFLECTIVE. Each level unlocks richer deliberation, but all levels share the same ⊕ machinery.
+- **Multi-agent** requires no new algebra — coordination *is* claim merging across agent boundaries. Agents communicate via **Channels** (named ⊕-accumulators), and when two agents commit to the same goal type, a **CommitmentArbiter** selects one winner by priority and competence; losers skip that cycle but still update from channel claims, so they naturally adjust.
+
+The only thing ⊕ does *not* give you is **deliberation** — the strategic, creative, non-monotonic act of deciding what to want. That is the one true primitive you must provide. It is where your agent's intelligence lives, and it is correctly outside the algebra.
+
+## Design Philosophy
+
+| Framework | Core metaphor | Asks |
+|-----------|--------------|------|
+| LangGraph | Control flow — the world can be orchestrated | *How do I wire steps correctly?* |
+| CrewAI | Social structure — intelligence from collaboration | *How do I assign roles?* |
+| AutoGen | Conversation — intelligence lives in dialogue | *How do I design dialogue?* |
+| **LIPAS** | **Algebra — intelligence is convergence under ⊕** | ***Under what conditions must a system become competent?*** |
+
+LIPAS believes: you will make mistakes, your agents will make mistakes, and the world will respond unpredictably.
+The only reliable path is to accumulate experience monotonically, never repeat the same failure blindly, and let convergence do the rest.
+
+## Documentation
+
+- **[The Reference Specification](docs/lipas-reference.md)** — operational definition: belief spaces, commitments, effects, morphisms, axioms, execution cycle.
+- **[Algebraic Calculus of Claim](docs/lipas-calculus.md)** — the algebraic foundation: how ⊕ derives the specification from first principles.
+
+
+
+# LIPAS
+
+**An agent framework built on algebra, not architecture.**
+
+> Most frameworks ask you to wire components together.
+>
+> LIPAS asks you to declare intent — and lets one operation, **⊕**, handle the rest.
+
+---
+
+## The 30-second version
+
+```python
+import asyncio
+from lipas.flow import Step, Pipeline
+from lipas.llm  import LLMAdapter, OllamaBackend
+
+llm = LLMAdapter(OllamaBackend(model="gemma4", timeout=300.0), verbose=True)
+the_text = "AI will not replace humans, but humans who use AI will replace those who don't."
+
+@Step(needs=['english_text'], produces=['chinese_draft'])
+async def translate(english_text: str) -> str:
+    return await llm.ask(
+            f'topic: Please translate it into Chinese naturally: "{english_text}"',
+            system="You are a translator providing only the most appropriate translation."
+               "Produce a focused, accurate translation. Every sentence must be relevant.",
+    )
+
+@Step(needs=['chinese_draft'], produces=['polished'])
+async def polish(chinese_draft: str) -> str:
+    return await llm.ask(
+            f'topic: Please polish this Chinese naturally: "{chinese_draft}"',
+            system="You are a polishing editor providing only the most appropriate polishment."
+               "Produce a focused, accurate polishment. Every sentence must be relevant.",
+    )
+
+pipeline = Pipeline(steps=[translate, polish], done_when='polished',)
+asyncio.run(pipeline.run(english_text=the_text))
+```
+
+That is a real, complete, runnable agent. No state machine. No edge list. No router config.
+
+Each function declares what it reads and what it writes.
+
+`Pipeline` threads context through, handles retries, and converges.
+
+---
+
+## Why another framework?
+
+Most agent frameworks give you a box of components — planners, memory stores, tool routers — and ask you to wire them together.
+
+The wiring is where bugs live.
+
+LIPAS starts from a different place: a single algebraic operation, **⊕** (claim merge).
+
+The practical consequences:
+
+- **You declare what the agent wants, not how it gets there.**
+  A pipeline is a set of steps with declared inputs and outputs. There is no control flow to wire, no state machine to draw.
+
+- **Failure handling writes itself.**
+  Every outcome — success or failure — is a Claim that merges into belief via ⊕. The agent cannot forget a lesson, and it provably stops repeating the same mistake.
+
+- **Complexity stays flat.**
+  Adding a new capability is one function and one `@Step` decorator. The algebra composes them; you don't reason about interactions.
+
+- **The LLM is just another claim source.**
+  Its output is unreliable — that's fine. ⊕ treats an LLM response exactly like a sensor reading: a Claim with a priority. Hallucinations are absorbed the same way as any other low-confidence signal.
+
+---
+
+## A fuller example — research pipeline with quality gate
+
+See [`examples/research_flow/research_app.py`](examples/research_flow/research_app.py)
+— a search → summarise → validate → refine pipeline with conditional branching via `when=` guards.
+— two plain functions, one line each. There is no router, no conditional edge, no explicit branch node.
+
+---
+
+## How it works — the algebra in brief
+
+**⊕ (claim merge)** is a join on a field-indexed product semilattice.
+
+```
+You supply:  deliberation  (what to want — your strategy, your intelligence)
+⊕ supplies:  everything else
+```
+
+From this one operation, the entire architecture is *derived*, not designed:
+
+| Concept | What it is |
+|---|---|
+| **Belief** | The cumulative fold of all Claims under ⊕. Monotonicity is a theorem. |
+| **Commitment** | A conative Claim with a priority field. Arbitration falls out of the semilattice order. |
+| **Effect** | An action that, when executed, produces new Claims — closing the perception-action loop. |
+| **Learning** | What happens when failure records fold back into belief via ⊕. Not a module — a consequence. |
+| **Adaptation** | The agent progresses through levels (REACTIVE → CAUTIOUS → STRATEGIC → REFLECTIVE) as belief accumulates. Each level unlocks richer deliberation; all share the same ⊕ machinery. |
+| **Multi-agent** | Coordination *is* claim merging across agent boundaries. No new algebra required. |
+
+The one thing ⊕ does *not* give you is **deliberation** — the creative act of deciding what to want. That is the true primitive you supply.
+
+It is where your agent's intelligence lives, and it belongs outside the algebra.
+
+---
+
+## Design philosophy
+
+| Framework | Core metaphor | The question it asks |
+|---|---|---|
+| LangGraph  | Control flow — orchestrate the world | *How do I wire steps correctly?* |
+| CrewAI     | Social structure — roles and crews | *How do I assign roles?* |
+| AutoGen    | Conversation — dialogue as intelligence | *How do I design the dialogue?* |
+| **LIPAS**  | **Algebra — intelligence is convergence under ⊕** | ***Under what conditions must a system become competent?*** |
+
+LIPAS is built on a single assumption: you will make mistakes, your agents will make mistakes, and the world will respond unpredictably. The only reliable path is to accumulate experience monotonically, never repeat the same failure blindly, and let convergence do the rest.
+
+You cannot "turn off" learning in LIPAS any more than you can remove addition from arithmetic — it is belief accumulation, and belief accumulation is what ⊕ does.
+
+---
+
+## Installation
+
+```bash
+pip install lipas
+```
+
+Requires Python 3.10. For local LLM support, install [Ollama](https://ollama.com) and pull a model:
+
+```bash
+ollama pull gemma4
+```
+
+---
+
+## License
+
+MIT

lipas-0.3.0/README.md

@@ -0,0 +1,220 @@
+# LIPAS
+
+**An agent framework built on algebra, not architecture.**
+
+> Everything is a Claim. One operation -- ⊕  -- derives the rest.
+>
+> Monotonicity, recording, and convergence are consequences -- not axioms.
+
+---
+
+## What You Actually Write
+
+Most of the algebra stays below the surface. The programming interface you touch daily is `lipas.flow` — a declarative pipeline where you describe **what each step needs** and **what it produces**, and the framework handles execution, failure, retries, and context threading.
+
+```python
+```
+
+That is a complete, runnable agent. There is no state machine, no edge list, no router config.
+
+You write one function per capability, declare its inputs and outputs, and `Pipeline` threads the context through ⊕ for you.
+
+The cognitive load is minimal: each function is a plain Python function whose signature names the context keys it reads, and whose return dict names the keys it writes.
+
+**You never manually route data, catch retry loops, or wire failure handlers — ⊕ absorbs every outcome and the pipeline converges.**
+
+---
+
+## What is LIPAS?
+
+Most agent frameworks give you a box of components — planners, memory stores, tool routers — and ask you to wire them together.
+
+LIPAS starts from a different place: a single algebraic operation.
+
+The practical consequence is that you _**stop writing glue**_ and start writing intent:
+
+- **You declare what the agent wants, not how it gets there.** A policy is a flow, which can be described as a YAML file of priorities and conditions. There is no control flow to wire, no state machine to draw, no edge cases to enumerate.
+- **Failure handling writes itself.** Every outcome — success or failure — is a Claim that merges into belief via ⊕. The agent accumulates experience monotonically: it cannot forget a lesson, and it provably stops repeating the same mistake.
+- **Complexity stays flat.** Adding a new capability is one handler function and one commitment entry. The algebra composes them; you don't have to reason about interactions.
+- **The LLM is just another claim source.** Its output is unreliable — fine. ⊕ treats an LLM response exactly like a sensor reading or a user input: a Claim with a priority. The algebra absorbs hallucinations the same way it absorbs any other low-confidence signal.
+
+---
+
+**⊕ (claim merge)** is a join on a field-indexed product semilattice.
+
+```
+You supply: deliberation (strategy)
+⊕ supplies: everything else
+```
+
+---
+
+From this one operation, the entire agent architecture is *derived*, not designed:
+
+- **Belief** is the cumulative fold of epistemic claims under ⊕. Monotonicity is a theorem, not an assumption.
+- **Commitment** is a conative claim with a priority field. Arbitration falls out of the semilattice order.
+- **Effect** is an action that, when executed, produces new claims — closing the perception-action loop.
+
+- **Learning** is what happens when effectual claims (failure records, outcome observations) are folded back into belief via ⊕. Every failed effect produces a (commitment_kind, OutcomeTag) record. When failures for a given kind exceed the caution threshold, the agent expects that failure and stops committing to it. This is not hard-coded retry logic — it is a threshold on a monotone counter that ⊕ maintains. Convergence toward competence is a consequence of belief monotonicity. Other frameworks either lack adaptation entirely or bolt on a learning module long after the fact. In LIPAS, learning is not a pluggable component, not a separate pipeline stage, not an external memory store — it is a mathematical consequence of Claim merging. You cannot "turn off" learning any more than you can remove addition from arithmetic; it is belief accumulation.
+- **Adaptation** is gradient: the agent progresses through adaptation levels (REACTIVE → CAUTIOUS → STRATEGIC → REFLECTIVE) as belief accumulates. A fresh agent is REACTIVE; after enough observations it becomes CAUTIOUS; with learned expectations it reaches STRATEGIC; with sufficient history for meta-reasoning it becomes REFLECTIVE. Each level unlocks richer deliberation, but all levels share the same ⊕ machinery.
+- **Multi-agent** requires no new algebra — coordination *is* claim merging across agent boundaries. Agents communicate via **Channels** (named ⊕-accumulators), and when two agents commit to the same goal type, a **CommitmentArbiter** selects one winner by priority and competence; losers skip that cycle but still update from channel claims, so they naturally adjust.
+
+The only thing ⊕ does *not* give you is **deliberation** — the strategic, creative, non-monotonic act of deciding what to want. That is the one true primitive you must provide. It is where your agent's intelligence lives, and it is correctly outside the algebra.
+
+## Design Philosophy
+
+| Framework | Core metaphor | Asks |
+|-----------|--------------|------|
+| LangGraph | Control flow — the world can be orchestrated | *How do I wire steps correctly?* |
+| CrewAI | Social structure — intelligence from collaboration | *How do I assign roles?* |
+| AutoGen | Conversation — intelligence lives in dialogue | *How do I design dialogue?* |
+| **LIPAS** | **Algebra — intelligence is convergence under ⊕** | ***Under what conditions must a system become competent?*** |
+
+LIPAS believes: you will make mistakes, your agents will make mistakes, and the world will respond unpredictably.
+The only reliable path is to accumulate experience monotonically, never repeat the same failure blindly, and let convergence do the rest.
+
+## Documentation
+
+- **[The Reference Specification](docs/lipas-reference.md)** — operational definition: belief spaces, commitments, effects, morphisms, axioms, execution cycle.
+- **[Algebraic Calculus of Claim](docs/lipas-calculus.md)** — the algebraic foundation: how ⊕ derives the specification from first principles.
+
+
+
+# LIPAS
+
+**An agent framework built on algebra, not architecture.**
+
+> Most frameworks ask you to wire components together.
+>
+> LIPAS asks you to declare intent — and lets one operation, **⊕**, handle the rest.
+
+---
+
+## The 30-second version
+
+```python
+import asyncio
+from lipas.flow import Step, Pipeline
+from lipas.llm  import LLMAdapter, OllamaBackend
+
+llm = LLMAdapter(OllamaBackend(model="gemma4", timeout=300.0), verbose=True)
+the_text = "AI will not replace humans, but humans who use AI will replace those who don't."
+
+@Step(needs=['english_text'], produces=['chinese_draft'])
+async def translate(english_text: str) -> str:
+    return await llm.ask(
+            f'topic: Please translate it into Chinese naturally: "{english_text}"',
+            system="You are a translator providing only the most appropriate translation."
+               "Produce a focused, accurate translation. Every sentence must be relevant.",
+    )
+
+@Step(needs=['chinese_draft'], produces=['polished'])
+async def polish(chinese_draft: str) -> str:
+    return await llm.ask(
+            f'topic: Please polish this Chinese naturally: "{chinese_draft}"',
+            system="You are a polishing editor providing only the most appropriate polishment."
+               "Produce a focused, accurate polishment. Every sentence must be relevant.",
+    )
+
+pipeline = Pipeline(steps=[translate, polish], done_when='polished',)
+asyncio.run(pipeline.run(english_text=the_text))
+```
+
+That is a real, complete, runnable agent. No state machine. No edge list. No router config.
+
+Each function declares what it reads and what it writes.
+
+`Pipeline` threads context through, handles retries, and converges.
+
+---
+
+## Why another framework?
+
+Most agent frameworks give you a box of components — planners, memory stores, tool routers — and ask you to wire them together.
+
+The wiring is where bugs live.
+
+LIPAS starts from a different place: a single algebraic operation, **⊕** (claim merge).
+
+The practical consequences:
+
+- **You declare what the agent wants, not how it gets there.**
+  A pipeline is a set of steps with declared inputs and outputs. There is no control flow to wire, no state machine to draw.
+
+- **Failure handling writes itself.**
+  Every outcome — success or failure — is a Claim that merges into belief via ⊕. The agent cannot forget a lesson, and it provably stops repeating the same mistake.
+
+- **Complexity stays flat.**
+  Adding a new capability is one function and one `@Step` decorator. The algebra composes them; you don't reason about interactions.
+
+- **The LLM is just another claim source.**
+  Its output is unreliable — that's fine. ⊕ treats an LLM response exactly like a sensor reading: a Claim with a priority. Hallucinations are absorbed the same way as any other low-confidence signal.
+
+---
+
+## A fuller example — research pipeline with quality gate
+
+See [`examples/research_flow/research_app.py`](examples/research_flow/research_app.py)
+— a search → summarise → validate → refine pipeline with conditional branching via `when=` guards.
+— two plain functions, one line each. There is no router, no conditional edge, no explicit branch node.
+
+---
+
+## How it works — the algebra in brief
+
+**⊕ (claim merge)** is a join on a field-indexed product semilattice.
+
+```
+You supply:  deliberation  (what to want — your strategy, your intelligence)
+⊕ supplies:  everything else
+```
+
+From this one operation, the entire architecture is *derived*, not designed:
+
+| Concept | What it is |
+|---|---|
+| **Belief** | The cumulative fold of all Claims under ⊕. Monotonicity is a theorem. |
+| **Commitment** | A conative Claim with a priority field. Arbitration falls out of the semilattice order. |
+| **Effect** | An action that, when executed, produces new Claims — closing the perception-action loop. |
+| **Learning** | What happens when failure records fold back into belief via ⊕. Not a module — a consequence. |
+| **Adaptation** | The agent progresses through levels (REACTIVE → CAUTIOUS → STRATEGIC → REFLECTIVE) as belief accumulates. Each level unlocks richer deliberation; all share the same ⊕ machinery. |
+| **Multi-agent** | Coordination *is* claim merging across agent boundaries. No new algebra required. |
+
+The one thing ⊕ does *not* give you is **deliberation** — the creative act of deciding what to want. That is the true primitive you supply.
+
+It is where your agent's intelligence lives, and it belongs outside the algebra.
+
+---
+
+## Design philosophy
+
+| Framework | Core metaphor | The question it asks |
+|---|---|---|
+| LangGraph  | Control flow — orchestrate the world | *How do I wire steps correctly?* |
+| CrewAI     | Social structure — roles and crews | *How do I assign roles?* |
+| AutoGen    | Conversation — dialogue as intelligence | *How do I design the dialogue?* |
+| **LIPAS**  | **Algebra — intelligence is convergence under ⊕** | ***Under what conditions must a system become competent?*** |
+
+LIPAS is built on a single assumption: you will make mistakes, your agents will make mistakes, and the world will respond unpredictably. The only reliable path is to accumulate experience monotonically, never repeat the same failure blindly, and let convergence do the rest.
+
+You cannot "turn off" learning in LIPAS any more than you can remove addition from arithmetic — it is belief accumulation, and belief accumulation is what ⊕ does.
+
+---
+
+## Installation
+
+```bash
+pip install lipas
+```
+
+Requires Python 3.10. For local LLM support, install [Ollama](https://ollama.com) and pull a model:
+
+```bash
+ollama pull gemma4
+```
+
+---
+
+## License
+
+MIT