Metadata-Version: 2.4
Name: artifacta
Version: 0.1.1
Summary: Universal experiment and artifact tracking — gain insights and optimize models with confidence
Author: Artifacta Contributors
License: Elastic License 2.0
Project-URL: Homepage, https://github.com/walkerbdev/artifacta
Project-URL: Documentation, https://github.com/walkerbdev/artifacta#readme
Project-URL: Repository, https://github.com/walkerbdev/artifacta
Project-URL: Issues, https://github.com/walkerbdev/artifacta/issues
Keywords: experiment-tracking,visualization,mlops,data-science
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: flask>=2.0.0
Requires-Dist: flask-cors>=3.0.0
Requires-Dist: pillow>=9.0.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: requests>=2.31.0
Requires-Dist: psutil>=5.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: pydocstyle>=6.3.0; extra == "dev"
Requires-Dist: sphinx>=7.0.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "dev"
Requires-Dist: sphinx-autodoc-typehints>=1.24.0; extra == "dev"
Requires-Dist: numpy>=1.24.0; extra == "dev"
Requires-Dist: matplotlib>=3.7.0; extra == "dev"
Requires-Dist: seaborn>=0.12.0; extra == "dev"
Requires-Dist: scikit-learn>=1.3.0; extra == "dev"
Requires-Dist: requests>=2.31.0; extra == "dev"
Requires-Dist: sqlalchemy>=2.0.0; extra == "dev"
Requires-Dist: pillow>=9.0.0; extra == "dev"
Requires-Dist: pytorch-lightning>=2.0.0; extra == "dev"
Requires-Dist: torch>=2.0.0; extra == "dev"
Requires-Dist: torchvision>=0.15.0; extra == "dev"
Requires-Dist: tensorflow>=2.13.0; extra == "dev"
Requires-Dist: reportlab>=4.0.0; extra == "dev"
Requires-Dist: av>=10.0.0; extra == "dev"
Requires-Dist: bump-my-version>=0.26.0; extra == "dev"
Dynamic: license-file

# Artifacta

**Universal experiment and artifact tracking — gain insights and optimize models with confidence.**

[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Elastic%202.0-green)](LICENSE)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

---

## ✨ Key Features

- 🌐 **Domain-agnostic** - Track any experiment comparing parameters, data, and outcomes
- 📊 **Automatic visualization** - Plots discovered from logged data structure
- 🔗 **Artifact tracking** - Track datasets, models, code, and results with full provenance
- 🔄 **Multi-run comparison** - Overlay time series and curves for easy comparison
- 🎯 **Hyperparameter analysis** - Automatically detect and analyze parameter impact on outcomes
- 💬 **AI assistant** - Chat interface for experiment insights (OpenAI, Anthropic, local LLMs)

---

## 🎨 Visual Overview

**Automatic Plot Discovery**

![Plots](docs/_static/Plots.gif)

Artifacta automatically generates visualizations based on your data shape and metadata. No manual plot configuration needed.

**Artifact Management**

![Artifacts](docs/_static/Artifacts_1.gif)

Browse and preview datasets, models, code, images, videos, and documents with built-in file viewers.

---

## 🚀 Quick Start

### Installation

#### Standard Installation

**Prerequisites:** Python 3.9+

```bash
# Clone the repository
git clone https://github.com/walkerbdev/artifacta.git
cd artifacta

# Install Python package
pip install -e .
```

**Note:** The UI is pre-built and bundled. No Node.js required.

#### Development Installation

**Prerequisites:** Python 3.9+, Node.js 16+

```bash
# Clone the repository
git clone https://github.com/walkerbdev/artifacta.git
cd artifacta

# Build UI from source
npm install && npm run build

# Install Python package
pip install -e .
```

### Start Tracking Server

```bash
artifacta ui
```

The web UI will be available at http://localhost:8000 (default).

You can customize host and port:

```bash
artifacta ui --host 0.0.0.0 --port 8000
```

**Development Mode:** Run with hot-reload for UI development:

```bash
artifacta ui --dev
```

### Log Your First Experiment

```python
import artifacta as ds

# Initialize a run
run = ds.init(
    project="my-project",
    name="experiment-1",
    config={"learning_rate": 0.001, "batch_size": 32}
)

# Log metrics during training
for epoch in range(10):
    train_loss = train_model()  # Your training code

    ds.log("metrics", ds.Series(
        index="epoch",
        fields={
            "train_loss": [train_loss],
            "epoch": [epoch]
        }
    ))

# Log artifacts (models, plots, etc.)
run.log_artifact("model.pt", "path/to/model.pt")
```

---

## 📚 Documentation

Full documentation available at: [User Guide](docs/user-guide.rst)

Build and serve docs locally:

```bash
pip install artifacta[dev]
cd docs && make html
python -m http.server 8001 --directory _build/html
```

Then navigate to http://localhost:8001

---

## 📊 Core Primitives

Artifacta provides rich primitives for structured logging:

- **Series** - Time series data (loss curves, accuracy over time)
- **Curve** - ROC curves, PR curves with AUC metrics
- **Distribution** - Histograms and distributions
- **Matrix** - Confusion matrices and heatmaps
- **Scatter** - 2D scatter plots (embeddings, parameter spaces)
- **BarChart** - Categorical comparisons
- **Table** - Structured tabular data

All primitives are automatically visualized in the Plots tab.

---

## 💻 Web UI Features

- **Plots** - Auto-generated visualizations with multi-run overlay
- **Sweeps** - Hyperparameter analysis with parallel coordinates
- **Artifacts** - File browser with preview for code, images, video, audio
- **Tables** - Metric aggregation and comparison tables
- **Lineage** - Visual artifact provenance graphs
- **Notebooks** - Rich text lab notebook with LaTeX support
- **Chat** - AI assistant for experiment analysis

---

## 💡 Examples

See [examples/](examples/) for runnable examples:

- **PyTorch MNIST** - Image classification with autolog
- **TensorFlow Regression** - Time series forecasting
- **A/B Testing** - Conversion rate analysis with statistical tests

Additional domain examples available in [tests/domains/](tests/domains/):

- Climate modeling, Computer vision, Finance, Genomics, Physics, Robotics, and more

**Run examples:**

```bash
source venv/bin/activate
python examples/ab_testing.py
```

---

## 🧪 Running Tests

Start the tracking server in one terminal:

```bash
source venv/bin/activate
artifacta ui
```

Run tests in another terminal:

```bash
source venv/bin/activate
pytest tests/
```
