{"id":32469474,"url":"https://github.com/davidlandup0/microtrax","last_synced_at":"2025-10-26T15:58:33.396Z","repository":{"id":314690399,"uuid":"1052486021","full_name":"DavidLandup0/microtrax","owner":"DavidLandup0","description":"Yet Another Experiment Tracking Library. Local, minimalist, micro experiment tracking for Machine Learning/Deep Learning workflows. No accounts, no setups. 3 lines to track.","archived":false,"fork":false,"pushed_at":"2025-10-20T11:57:06.000Z","size":2710,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-20T13:29:46.354Z","etag":null,"topics":["deep-learning","experiment-tracking","machine-learning","scientific-computing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DavidLandup0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-08T05:58:45.000Z","updated_at":"2025-10-20T11:57:10.000Z","dependencies_parsed_at":"2025-09-14T06:18:17.588Z","dependency_job_id":"30788736-7f59-4403-aae3-eb0e1945ff60","html_url":"https://github.com/DavidLandup0/microtrax","commit_stats":null,"previous_names":["davidlandup0/microtrax"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DavidLandup0/microtrax","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidLandup0%2Fmicrotrax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidLandup0%2Fmicrotrax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidLandup0%2Fmicrotrax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidLandup0%2Fmicrotrax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DavidLandup0","download_url":"https://codeload.github.com/DavidLandup0/microtrax/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidLandup0%2Fmicrotrax/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281130763,"owners_count":26448690,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-26T02:00:06.575Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","experiment-tracking","machine-learning","scientific-computing"],"created_at":"2025-10-26T15:58:31.748Z","updated_at":"2025-10-26T15:58:33.387Z","avatar_url":"https://github.com/DavidLandup0.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\u003ch1\u003emicrotrax\u003c/h1\u003e\u003c/div\u003e\n\u003cdiv align=\"center\"\u003e\u003ch6\u003eYet Another Experiment Tracking Library\u003c/h6\u003e\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\u003ch3\u003eLocal, minimalist, micro experiment tracking for Machine Learning/Deep Learning workflows.\u003c/h1\u003e\u003c/div\u003e\n\n\u003chr\u003e\n\n\u003cdiv align=\"center\"\u003e\nFree. Fully local. Lightweight.\n\u003c/div\u003e\n\u003chr\u003e\n\nNo accounts, no setups. 3 lines to track.\n\n`microtrax` attempts to be a modern, minimalist library for experiment tracking. Inspired by TensorBoard.\n\n\u003cdiv align=\"center\"\u003e\u003ch2\u003eQuickstart\u003c/h1\u003e\u003c/div\u003e\n\n```bash\n$ pip install microtrax\n```\n\n```python\nimport microtrax as mtx\n\nepochs = 10\nmtx.init('./logbook_dir') #, optionally also track_resources=True)\n\nfor i in range(epochs):\n    mtx.log({\n        \"step\": i,\n        \"loss\": epochs-i\n    })\n\nmtx.finish()\n```\n\nThen serve the dashboard:\n\n```\n$ mtx serve -f ./logbook_dir\n```\n\nThis automatically starts both the FastAPI backend and React frontend!\n\n\u003cimg width=\"1364\" height=\"636\" alt=\"image\" src=\"https://github.com/user-attachments/assets/08d3b4be-d47e-45c5-a8d1-2414c91c8d8e\" /\u003e\n\nIt's called a quickstart as if there's anything else you can do with it. Actually, that's pretty much it.\n\n\u003cdiv align=\"center\"\u003e\u003ch2\u003eDesign Philosophy\u003c/h2\u003e\u003c/div\u003e\n\n- Free forever.\n- Simplicity \u003e feature-richness.\n- Research-experience first.\n- Framework agnostic - no specialized adapters for different libraries nor ecosystem favoritism. Log whatever.\n- Lightweight footprint. No hogging the CPU or memory.\n- Easily extendable (standard stack + simple to add new components/routes)\n- No setups, no accounts, no enterprise versions.\n\n\u003cdiv align=\"center\"\u003e\u003ch2\u003eLearning microtrax in 10 seconds\u003c/h2\u003e\u003c/div\u003e\n\n- **Experiment:** whatever happens between `mtx.init()` and `mtx.finish()`, housing a series of `mtx.log()`s.\n- **Logbook:** Collection of experiments in a log directory.\n- **Dashboard:** Where your visualizations go. You can select which experiments to visualize and overlay from the logbook.\n\nNo need to learn anything else to use `microtrax`.\n\n\u003cdiv align=\"center\"\u003e\u003ch2\u003eCLI Usage\u003c/h2\u003e\u003c/div\u003e\n\nAfter installation, you can use the `mtx` command:\n\n```bash\n# Start the dashboard \nmtx serve -f ./logbook_dir -p 8080\n\n# Start with Docker Compose\nmtx serve -f ./logbook_dir --docker\n\n# List all experiments in a directory\nmtx list -f ./logbook_dir\n\n# Serve with custom host/port\nmtx serve -f ./logbook_dir --host 0.0.0.0 -p 8080\n```\n\n**Commands:**\n- `mtx serve` - Start the interactive dashboard web server\n- `mtx list` - List all experiments in the specified directory\n\n**Options:**\n- `-f, --logdir` - Directory containing experiments (default: ~/.microtrax)\n- `-p, --port` - Port to run dashboard on (default: 8080)  \n- `--host` - Host to bind to (default: localhost)\n- `--docker` - Run using Docker Compose instead of local servers\n\n\n\u003cbr\u003e\n\n# microtrax - Bird's Eye View\n\nFrom a bird's eye view, `microtrax` has four main components:\n\n- **Core:** Core operations like `mtx.init()`, `mtx.log()` and `mtx.finish()`, as well as handling of I/O\n- **CLI:** Runner for the CLI commands like `mtx list` and `mtx serve`\n- **Backend:** FastAPI server + routers for exposing a logdir's logs\n- **Frontend:** React frontend for visualizing data provided by the server via Plotly\n\n### Why React + FastAPI and not something \"simpler\"? \n\nBecause this is a hackable, extendable, simple format. We want to make it as easy as possible to extend and tweak the library.\nProprietary formats, uncommon libs or \"simplifying\" by obscurity go against the core principles of the library.\n\n- Need a new widget -\u003e Add a single React component in `/frontend/src/components`\n- Need a new server endpoint -\u003e Add a single endpoint in FastAPI's routers in `/backend/routers`\n\nA highly standard stack ensures that the widest number of users can easily and comfortably understand and extend the library as needed.\n\n\n```\n\n  ┌─────────────────────────────────────────────────────────────────────────────┐\n  │                               microtrax                                     │\n  └─────────────────────────────────────────────────────────────────────────────┘\n\n  ┌─────────────────┐      ┌───────────────────┐    ┌─────────────────────────────┐\n  │   User Code     │      │   File System     │    │        Dashboard            │\n  │                 │      │                   │    │                             │\n  │  mtx.init()     │─────▶│  ~/.microtrax/    │◀───│ ┌─────────────────────────┐ │\n  │  mtx.log({...}) │      │    experiments/   │    │ │    React Frontend       │ │\n  │  mtx.finish()   │      │    resources/     │    │ │    (Port 8080)          │ │\n  │                 │      │                   │    │ │  - Plot visualizations  │ │\n  └─────────────────┘      │  exp_id.jsonl     │    │ │  - Experiment browser   │ │\n                           │  (w/ base64 imgs) │    │ │  - Settings panel       │ │\n  ┌───────────────────┐    │  resources.jsonl  │    │ └─────────────────────────┘ │\n  │   Core Module     │    │                   │    │             │               │\n  │                   │───▶│                   │    │           HTTP              │\n  │ • Experiment      │    └───────────────────┘    │             │               │\n  │ • ResourceTracker │                             │ ┌─────────────────────────┐ │\n  │ • I/O Utils       │   ┌──────────────────┐      │ │   FastAPI Backend       │ │\n  │ • Image Processing│   │       CLI        │──────│ │   (Port 8080)           │ │\n  └───────────────────┘   │                  │      │ │                         │ │\n                          │  mtx serve       │      │ │  /api/experiments       │ │\n                          │  mtx list        │      │ │  /api/plots             │ │\n                          └──────────────────┘      │ │  /api/images            │ │\n                                                    │ │  /api/plot-options      │ │\n                                                    │ └─────────────────────────┘ │\n                                                    └─────────────────────────────┘\n\n  Data Flow:\n  User Code ─\u003e JSONL -\u003e File System -\u003e Backend -\u003e JSON -\u003e Frontend -\u003e User\n```\n\n### Frontend Serving\n\nThe frontend is served as static files on the same port as the backend (`localhost:8080`).\nYou can separately build the frontend for hot reloads during development of new features if you're customizing the library.\n\n# Docker Compose\n\nYou can also run the `microtrax` dashboard through Docker Compose for containerized deployment.\n\n## Setup\n\n1. Configure your experiment log directory in `.env`:\n```bash\n# Directory where experiment logs are stored\nMICROTRAX_LOGDIR=./my_experiments\n```\n\n2. Run the stack:\n```bash\ndocker-compose up\n```\n\nThis will start:\n- **Backend API and frontend served** on port 8080\n\n## Configuration\n\nThe `MICROTRAX_LOGDIR` environment variable specifies where your experiment logs are stored on the host machine. This directory is mounted into the backend container at `/data`.\n\nDefault: `~/.microtrax` if not specified\n\n## Access\n\n- Dashboard: http://localhost:8080\n- Backend API: http://localhost:8080\n\nThe frontend handles routing and proxies `/api/*` requests to the backend automatically.\n\n# Contributing\n\nWe welcome contributions to `microtrax`! \nIt's community-first, so any and every issue and idea will be considered.\nThis guide will help you get started if you'd like to propose a change.\n\n## Getting Started\n\n1. **Fork and clone the repository**\n    \n```bash\n$ git clone https://github.com/yourusername/microtrax.git\n$ cd microtrax\n```\n\n2. Set up development environment\n\n```bash\n# Install Python dependencies\n$ pip install microtrax\n$ pip install pytest ruff\n\n# Install and build frontend\n$ cd microtrax/frontend\n$ npm install\n$ npm run build\n```\n\n3. Run tests\n\n```bash\n# Python tests\npytest\n# Format code\nmake format\n```\n\n## Development Workflow\n\n### Backend Changes\n\n- Location: `/microtrax/backend/`\n- For routers: `/backend/routers/`\n- For endpoints: `/backend/routers/router_name.py`\n- For business logic: `/backend/services/`\n- For data models: `/backend/domain/schemas.py`\n\n### Frontend Changes\n\n- Location: `/microtrax/frontend/src/`\n- For new components: `/frontend/src/components/`\n\n### Core Changes\n\n- Location: `/microtrax/core.py`, `/microtrax/io_utils.py`\n- Experiment tracking logic\n- File I/O operations\n- Image processing\n\n### Code Standards\n- Python: Follow PEP 8, use type hints, run ruff for linting\n\n\n### Submitting Changes\n\n1. Create a feature branch\n```\ngit checkout -b feature/your-feature-name\n```\n\n2. Make your changes\n3. Test\n4. Submit a pull request\n\n### Questions?\n\n- Check existing issues on GitHub\n- Start a discussion for feature ideas\n\n# Citation\n\nIf you happen to use `microtrax` for your research, and publish your results - we'd appreciate a citation~\n\n```\n@misc{landup2025microtrax,\n  title={microtrax},\n  author={David Landup},\n  year={2025},\n  howpublished={\\url{https://github.com/DavidLandup0/microtrax/}},\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidlandup0%2Fmicrotrax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidlandup0%2Fmicrotrax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidlandup0%2Fmicrotrax/lists"}