---
title: README
emoji: 📉
colorFrom: purple
colorTo: pink
sdk: static
pinned: false
license: apache-2.0
---

<h1 align="center">Nucleoid</h1>

![Nucleoid_Banner_v2](https://cdn-uploads.huggingface.co/production/uploads/65be6fe131e7709efb35eea1/OMB1Pb1CQgNBWTb0aEn03.png)

<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.