# Projects (Tellurio Studio)

```{warning}
Before running any code, ensure you are logged in to the Afnio backend (`afnio login`).
See [Logging in to Afnio Backend](login) for details.
```

On [Tellurio Studio](https://platform.tellurio.ai/) the top-level unit is an
**Organization**. An Organization contains multiple Projects; Projects in turn
group Runs, artifacts, and collaborators so teams can manage experiments, share
results, and control access to datasets and checkpoints.

Why use Projects:

- Organize related experiments and checkpoints in a single namespace.
- Share experiments with teammates by adding project members.
- Manage visibility and access control for reproducibility and collaboration.

```{note}
Billing is handled at the Organization level — usage (Runs, optimization hours,
storage, etc.) is billed to the parent Organization.
```

---

## Creating and Managing Projects

You can create and manage projects from the [Tellurio Studio](https://platform.tellurio.ai/)
UI (**Projects → Create new Project**) or programmatically via
[`afnio.tellurio.project`](../../generated/afnio.tellurio.project) helpers.

```{note}
[`afnio.tellurio`](../../generated/afnio.tellurio) is the client module you use
to interact with [Tellurio Studio](https://platform.tellurio.ai/): login, create
or retrieve [Projects](#creating-and-managing-projects), create
[Runs](runs_and_experiments.md#creating-a-run), log metrics, and upload artifacts.
```

`te.init(...)` (see [Runs and Experiments](runs_and_experiments)) will
automatically create a [`Project`](../../generated/afnio.tellurio.project) if it does
not exist; when auto-creating, Afnio uses a conservative default visibility
(`RESTRICTED`). If you need a different visibility, or want to invite members to the
project, create the project explicitly in the web UI or via the
[`afnio.tellurio.project`](../../generated/afnio.tellurio.project) APIs before
creating your [Run](runs_and_experiments.md#creating-a-run).

**Example: create a project programmatically**

```python
from afnio.tellurio.project import create_project

proj1 = create_project(
    namespace_slug="username_or_org",
    display_name="My Project",
    visibility="TEAM",
)
print(f"Created project: {proj1.display_name} (UUID: {proj1.uuid})")
```

_Output:_

```output
Created project: My Project (UUID: ff93c442-514a-4874-a3a2-4cd178810ced)
```

**Example: create or retrieve a project programmatically**

```python
from afnio.tellurio.project import get_project

proj2 = get_project(
    namespace_slug="username_or_org",
    project_slug="my-project",
)
print(f"Retrieved project: {proj2.display_name} (UUID: {proj2.uuid})")
```

_Output:_

```output
Retrieved project: My Project (UUID: ff93c442-514a-4874-a3a2-4cd178810ced)
```

### Project visibility

Projects support several visibility levels that control who can read and write
within a Project. Use the table below to pick the appropriate visibility for
collaboration or sharing:

| Visibility           | Read access                                                | Write access                                               |
| -------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- |
| RESTRICTED (default) | Only explicit project members (users added to the project) | Only explicit project members (users added to the project) |
| TEAM                 | Any member of the parent organization                      | Any member of the parent organization                      |
| PUBLIC               | Any authenticated user (login required)                    | Any member of the parent organization                      |
| OPEN                 | Anyone, including anonymous users                          | Anyone, including anonymous users                          |

### Project Members and Collaboration

Project members are users explicitly added to a [`Project`](../../generated/afnio.tellurio.project)
via the [Tellurio Studio](https://platform.tellurio.ai/) web UI
(**Projects → [Your Project] → Overview → Members → Add new Member**).
Members can be granted read and write access according to the project's visibility
and membership settings. Use project membership to give teammates access to runs,
logs, and artifacts without making experiments public.

### Recommended Workflow:

- Create or select a Project for your experiments.
- Use `te.init(...)` or the [`afnio.tellurio`](../../generated/afnio.tellurio) helpers
  to start [Runs](runs_and_experiments.md#creating-a-run) within that project so logs,
  costs, and artifacts are associated automatically.
- When you need fine-grained control (team onboarding, public release), manage
  visibility and members in the [Tellurio Studio](https://platform.tellurio.ai/) UI
  or via the [`afnio.tellurio.project`](../../generated/afnio.tellurio.project) API.

---

## Further reading

- [Runs and Experiments](runs_and_experiments)
- [Trainer](trainer)