Initial commit

.github/pull_request_template.md

@@ -0,0 +1,21 @@
+## Changes
+
+> What changes does this PR introduce? Link to the issue if applicable.
+
+## Blocked by
+
+> Which PRs need to be merged before this PR can be merged?
+
+## Testing
+
+> How was this PR tested? Make sure to mark the checkboxes and add more based on your testing. It may be helpful to write a testing plan prior to finishing the PR.
+
+- [ ]
+
+## Reviewing
+
+> How should the reviewer review and test this PR?
+
+## Documentation
+
+> How have any major architectural decisions and changes in this PR been documented?

.github/workflows/lint.yml

@@ -0,0 +1,47 @@
+name: Cartesia Python CI
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      # all python files
+      - '**/*.py'
+      # This file
+      - '**/lint.yml'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - '**/*.py'
+      # This file
+      - '**/lint.yml'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+
+  Linting:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: actions/cache@v2
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip
+
+      - name: Install Dependencies
+        run: |
+          make install-dev
+
+      - name: Lint with ruff
+        run: |
+          make lint

.gitignore

@@ -0,0 +1,184 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+*.dylib
+*.metallib
+.Python
+cartesia-mlx/build/
+cartesia-metal/build
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Logs
+logs/
+speed.py
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Ruff cache
+.ruff_cache/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# JetBrains IDEs
+.idea/
+.vscode/
+
+# dependencies
+node_modules
+.pnp
+.pnp.js
+.yarn
+
+# testing
+coverage
+
+# next.js
+.next/
+out/
+.swc/
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env
+.env*.local
+
+# turbo
+.turbo
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# secrets
+*.secrets
+
+# Local .terraform directories
+**/.terraform/*
+
+# .tfstate files
+*.tfstate
+*.tfstate.*

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+# NOTE: These versions should match those in requirements-dev.txt
+repos:
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.4.10
+  hooks:
+    # Run the linter.
+    - id: ruff
+      args: [ --fix ]
+    # Run the formatter.
+    - id: ruff-format
+- repo: https://github.com/timothycrosley/isort
+  rev: 5.13.2
+  hooks:
+  -   id: isort

CODEOWNERS

@@ -0,0 +1 @@
+@ad12 @nimz @tobiaskatsch

CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing
+
+Much of this guide was adopted from [AXLearn](https://github.com/apple/axlearn/blob/main/CONTRIBUTING.md).
+
+## General Guidelines
+1. Please do not commit broken code to any branch.
+1. Only commit stable config files. Config files that are in development should not be committed.
+1. Use pull requests (PR) to the merge in code. Do not develop on the main branch.
+
+## Coding Style
+
+We follow [the Google Python Style Guide](https://google.github.io/styleguide/pyguide.html).
+
+To avoid confusion around naming, respect code consistency in the repo, including but not limited to naming conventions and code structure.
+
+If you have not already, we recommend [setting up `pre-commit`](docs/01-start.md#optional-additional-setup-for-developers), which runs some of the linters/formatters prior to each commit. The same checks will be required to pass in CI, so this will help make the development process smoother.
+
+### Type Annotations
+
+Functions and methods must be annotated with types. We use [pytype](https://google.github.io/pytype/user_guide.html) for type checking.
+
+## Code Review Process
+
+### Author
+
+All PRs must be made with the default template provided in the repository.
+
+Before embarking on a major PR, send out a sketch PR (including the high level design notes in the PR description) to solicit feedback first.
+
+It is more manageable for both the author and reviewers to have small PRs that can be quickly reviewed and merged.
+
+When selecting multiple reviewers, use "Assignees" to indicate that approvals from specific
+reviewers are required before merging.
+
+The PR authors are expected to reply to each comment they have addressed, e.g., with "Done".
+However, they should refrain from resolving the comments -- instead, let the reviewers do so.
+
+When addressing a comment, pay attention to other places where the same comment may apply, so that
+the reviewer does not have to repeat the comment.
+
+When a PR is ready for another round of review, click [**re-request review**](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review) to notify the reviewer.
+
+Although not strictly enforced, a general etiquette is to wait for all reviewers who have left comments to approve the PR prior to merging, even if the PR has already received an approval.
+
+In some cases, the comments may be "nits" and appropriate for addressing in follow-up PRs. We encourage authors to give a heads up to reviewers prior to merging a PR with unresolved comments by leaving PR comments (e.g. "Will address in a follow-up") as well as [leaving a TODO](#leaving-todos) where applicable.
+
+### Reviewer
+
+People on the team should feel free to add themselves as reviewers and/or to assignees.
+
+Consider prioritizing reviews over writing one's own code.
+This will make the entire team more productive.
+
+Code review does not end with merge of the PR.
+Reviewers should feel free to add comments after the merge, which can be addressed in follow-up PRs.
+
+## Attributions
+
+Code that refers to (or is adapted from) other sources must explicitly reference the original source by providing a [link in the docstring](https://github.com/apple/axlearn/blob/669f0cae6249e165caa1a94cf64b12e77bf4cfdf/axlearn/common/attention.py#L360-L365) of the corresponding function, class, etc.
+
+Code that is adapted from papers should have clear `Reference:` section in the docstring that provides a complete reference (with link) to the original paper. Links to ArXiv papers are preferred to avoid paywalls.
+
+## Leaving TODOs
+
+In some cases it's useful to track future work ("TODOs").
+TODOs should have the format `TODO(username1,username2)` indicating the contributor(s) responsible for addressing the TODO.
+Please use your actual GitHub username as opposed to an alias to avoid ambiguity.
+
+For larger work items, consider creating a GitHub issue to track progress.