| --- |
| title: README |
| emoji: 📉 |
| colorFrom: purple |
| colorTo: pink |
| sdk: static |
| pinned: false |
| license: apache-2.0 |
| --- |
| |
| <h1 align="center">Nucleoid</h1> |
|
|
|  |
|
|
| <p align="center"> |
| <b>Logic Language for LLMs</b> |
| </p> |
|
|
| Hallucinations are a major challenge in LLM reasoning because natural language is unstructured. By nature, LLMs are pattern engines that reason more effectively over structured entities and relationships, enabling more reliable, near-deterministic results. |
|
|
| Nucleoid is designed with a minimally tokenized syntax for logic representation and a declarative execution model, eliminating the need for LLMs to manually manage control flow, state propagation, and other imperative constructs. In addition, Nucleoid is a next-generation logic programming language built on structured objects and their relationships, extending the traditional Knowledge Graph. |
|
|
| - **Near-Deterministic:** Structured, reliable reasoning. |
| - **Logic Graph:** Executable knowledge graph. |
| - **Explainability:** Transparent, traceable decisions. |
|
|
| <div align="center"> |
| <table> |
| <tr> |
| <th colspan="2">Nucleoid Runtime</th> |
| </tr> |
| <tr> |
| <th width="300">🦀 Rust-based</th> |
| <th width="300">⚡ LLM-based</th> |
| </tr> |
| <tr> |
| <td> |
| <b>Programming Language Runtime:</b> Implements the language specification by executing declarative statements. |
| </td> |
| <td> |
| <b>Fine-Tuned LLM:</b> Fine-tuned on synthesized datasets derived from the language specification. |
| </td> |
| </tr> |
| <tr> |
| <td align="center"><a href="https://github.com/NucleoidAI/Nucleoid">github.com/NucleoidAI/Nucleoid</a></td> |
| <td align="center"><a href="https://huggingface.co/nucleoid">huggingface.co/nucleoid</a></td> |
| </tr> |
| </table> |
| </div> |
| |
| ### Hello World |
|
|
| **Socrates is mortal without being told so** |
|
|
| ```nuc |
| # There is a Human type with a name |
| class Human(name: str): |
| this.name = name |
| |
| # Every human is mortal |
| $Human.mortal = true |
| |
| # Socrates is a Human |
| socrates = Human("Socrates") |
| |
| # Therefore, Socrates is mortal |
| assert(socrates.mortal, true) |
| ``` |
|
|
| --- |
|
|
| ## Language Reference |
|
|
| [**docs/reference.md**](https://github.com/NucleoidAI/Nucleoid/blob/rust/docs/reference.md) is the language reference: statements and state, variables and dependencies, expressions, types and instances, properties, class-level rules, blocks and scope, control flow, functions, transactions, built-in objects, error messages, and a syntax summary. |
|
|
| It is assembled from the NUC documents in [`/docs`](https://github.com/NucleoidAI/Nucleoid/blob/rust/docs/), indexed by [NUC 0](https://github.com/NucleoidAI/Nucleoid/blob/rust/docs/nuc-0000.md) with the conventions in [NUC 1](https://github.com/NucleoidAI/Nucleoid/blob/rust/docs/nuc-0001.md). `nucleoid.spec.md` is normative; where the two disagree, the specification wins. |
|
|
| [**docs/examples.md**](https://github.com/NucleoidAI/Nucleoid/blob/rust/docs/examples.md) covers the same ground as complete programs, each one runnable as written. |
|
|
| A Nucleoid program is a set of statements that remain true. An assignment is not an instruction that runs once and finishes, it is a relationship the runtime records and maintains. |
|
|
| **An assignment states a relationship, not a result** |
|
|
| ```nuc |
| a = 1 |
| b = a + 2 |
| |
| a = 3 |
| |
| assert(b, 5) |
| ``` |
|
|
| `b` is never stale. It is the sum of `a` and `2`, so changing `a` brings it up to date, and the same holds for properties, class-level rules and everything else the reference covers. |
|
|
| Every example in the reference is executable: `tests/reference.md` is its executable form and runs under `cargo test`, as do the snippets on this page. |
