> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understanding triples, entities, indexes, and graphs in Neode

## Triples

A **triple** is the fundamental unit of knowledge in Neode. It represents a single fact as three parts:

| Component     | Description                  | Example       |
| ------------- | ---------------------------- | ------------- |
| **Subject**   | The entity the fact is about | "Tesla"       |
| **Predicate** | The relationship or property | "founded\_by" |
| **Object**    | The value or related entity  | "Elon Musk"   |

This structure follows the [RDF](https://www.w3.org/RDF/) standard used in semantic web technologies.

### Object Types

Objects can be one of two types:

<Columns cols={2}>
  <Card title="Entity" icon="cube">
    Another entity that can have its own triples. Use for people, companies, places, concepts.

    ```json theme={null}
    {
      "object": "Elon Musk",
      "object_type": "entity"
    }
    ```
  </Card>

  <Card title="Literal" icon="text">
    A value like a date, number, or text. Use for attributes and properties.

    ```json theme={null}
    {
      "object": "2003",
      "object_type": "literal"
    }
    ```
  </Card>
</Columns>

### Confidence Scores

Each triple has a **confidence** score (0-1) indicating reliability:

* `0.9-1.0` - Verified facts from authoritative sources
* `0.7-0.9` - High confidence from reliable sources
* `0.5-0.7` - Moderate confidence, may need verification
* `<0.5` - Low confidence, treat as uncertain

### Sources

Triples can include a **source** URL for provenance tracking:

```json theme={null}
{
  "subject": "SpaceX",
  "predicate": "founded_year",
  "object": "2002",
  "object_type": "literal",
  "confidence": 0.95,
  "source": "https://en.wikipedia.org/wiki/SpaceX"
}
```

### Relationships and input rules

The **predicate** is the relationship or property (e.g. `founded`, `headquarters_in`, `founded_year`). Prefer **snake\_case** and consistent naming within an index. When creating triples you must provide **subject**, **predicate**, **object**, **object\_type** (`"entity"` or `"literal"`), and **index\_id**. Optional: **confidence** (0–1), **source** (URL), **graph\_id**. Subject and object are strings (entity names or literal values).

Relationships and the data you add are **scoped to the index**: each index has its own entities and triples, so predicate and entity names don't collide across indexes and you can use different naming or relationship styles per index.

***

## Entities

An **entity** represents a distinct thing in your knowledge graph - a person, company, place, concept, or any noun that can have facts about it.

### Automatic Creation

Entities are automatically created when you store triples. When you create a triple with subject "Tesla", Neode:

1. Checks if an entity named "Tesla" exists in your index
2. Creates a new entity if not found
3. Links the triple to the entity via `subject_entity_id`

The same happens for objects with `object_type: "entity"`.

### Entity Disambiguation

Within an **index**, entity names are disambiguated automatically. If you store triples about "Apple" (the company) and "Apple" (the fruit), they'll be treated as the same entity unless in different indexes.

<Tip>
  Use separate indexes for different domains to avoid entity confusion. For example, one index for "Tech Companies" and another for "Food & Agriculture".
</Tip>

### Entity Properties

Entities can have:

| Property      | Description                              |
| ------------- | ---------------------------------------- |
| `name`        | The canonical name                       |
| `description` | A text description (can be AI-generated) |
| `avatar_url`  | An image URL for display                 |

***

## Indexes

An **index** is a namespace for organizing entities and their triples. Think of it as a separate knowledge base or project.

### Why Use Indexes?

* **Separation**: Keep different projects isolated
* **Disambiguation**: "Apple" in your tech index is different from "Apple" in your food index
* **Access Control**: Indexes can be public or private
* **Organization**: Group related knowledge together

### Public vs Private

| Type        | Visibility                                     | Use Case                              |
| ----------- | ---------------------------------------------- | ------------------------------------- |
| **Private** | Only you can access                            | Personal projects, sensitive data     |
| **Public**  | Visible in [Explore](https://neode.ai/explore) | Shared knowledge, community resources |

### Creating an Index

```bash theme={null}
curl -X POST https://neode.ai/api/indexes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Technology Companies",
    "description": "Facts about major tech companies and their products"
  }'
```

***

## Graphs

A **graph** groups related triples together within an index. While indexes separate different knowledge domains, graphs organize triples within a domain.

### Use Cases for Graphs

* **Sessions**: Group triples generated in one session
* **Sources**: Group triples extracted from the same document
* **Topics**: Group triples about a specific topic
* **Versions**: Track different versions of knowledge

### Example

```bash theme={null}
# Create a graph for a specific research session
curl -X POST https://neode.ai/api/graphs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "SpaceX Research - Jan 2026",
    "description": "Facts gathered about SpaceX Starship program",
    "index_id": "YOUR_INDEX_ID"
  }'
```

Then reference the graph when creating triples:

```json theme={null}
{
  "subject": "Starship",
  "predicate": "first_orbital_flight",
  "object": "2025",
  "object_type": "literal",
  "graph_id": "GRAPH_ID",
  "index_id": "INDEX_ID"
}
```

***

## Data Model Summary

```
Index (namespace)
├── Entity (thing)
│   ├── name
│   ├── description
│   └── avatar_url
├── Graph (grouping)
│   └── name, description
└── Triple (fact)
    ├── subject → subject_entity_id
    ├── predicate
    ├── object → object_entity_id (if entity)
    ├── object_type (entity | literal)
    ├── confidence
    ├── source
    └── graph_id (optional)
```

<Card title="Ready to Start?" icon="rocket" href="/quickstart">
  Follow the quickstart guide to create your first knowledge graph.
</Card>