# The whole API surface, in one page

The API is small on purpose. Three things, and you have seen most of the platform.

```python
import eugo.hpc

# 1. The decorator: on a function it makes a task, on a class an actor
@eugo.hpc.distribute
def work(x):
    return x * 2

# 2. get() turns futures into values
future = work(21)
value = eugo.hpc.get(future)          # 42

# 3. options() sets per-call resource requirements
big = work.options(num_cpus=4, num_gpus=1)(21)
```

:::note `eugo` alone gives you nothing
The top-level `eugo` namespace is deliberately empty. `import eugo.hpc` is the import you want.
:::

## Why the surface is this small

Most distributed frameworks put mechanics at every call site: a `.remote()`, an explicit executor, a
context manager. That makes [cluster](/glossary/cluster) code visually distinct from ordinary code, which sounds like
honesty but reads as noise: the analysis gets buried in plumbing.

Eugo puts the decision at the *definition* site instead. A function is either distributed or it is not,
declared once. Call sites then look like ordinary Python:

```python
futures = [work(x) for x in items]
```

That is a list comprehension. It is also a thousand-task [fan-out](/glossary/fan-out) across a cluster.

## The one thing that changes

Decorating a function changes what calling it *returns*.

| | Plain function | Distributed function |
| --- | --- | --- |
| Returns | The value | A **future** |
| When the body runs | Immediately, inline | Later, on a worker |
| Blocks the caller | Yes | No |

A [future](/glossary/future) is a handle to a result that does not exist yet. Your code keeps running; `get()` is where you
wait.

Everything else in this course follows from that single change.

## Where each piece is covered

| Piece | Lesson |
| --- | --- |
| Tasks and the decorator | [Your first distributed task](./02-your-first-task.mdx) |
| Futures and `get()` | [Futures, and when to call get()](./03-futures-and-get.mdx) |
| Many tasks at once | [Parallel fan-out](./04-parallel-fan-out.mdx) |
| `options()` | [Requesting CPUs and GPUs](./05-resource-options.mdx) |
| Actors | [Distributed objects that hold state](./06-actors.mdx) |

## Ray, underneath

Eugo's distributed execution is built on Ray, deliberately hidden behind this smaller surface.

Worth knowing for two reasons: Ray's concepts (tasks, [actors](/glossary/actor), object refs) map onto what you are
learning, and its documentation can be a useful reference for edge cases. You do not need to know Ray
to use Eugo, and the hidden parts are hidden because managing them by hand is what the platform is for.

---

Source: https://university.eugo.io/lesson/distributed-python-with-eugo-hpc/the-api-surface