{"id":15038380,"url":"https://github.com/zachgrayio/swift-tensorflow-starter","last_synced_at":"2025-04-09T23:40:54.776Z","repository":{"id":90044439,"uuid":"131381722","full_name":"zachgrayio/swift-tensorflow-starter","owner":"zachgrayio","description":" STS: A Dockerized, Swift Package Manager enabled starter repository for Swift for TensorFlow projects.","archived":false,"fork":false,"pushed_at":"2018-05-07T19:48:22.000Z","size":55,"stargazers_count":45,"open_issues_count":6,"forks_count":4,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-24T01:35:13.359Z","etag":null,"topics":["docker","starter-project","swift","swift-4","swift-for-tensorflow","swiftpm","tensorflow"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zachgrayio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-28T06:49:37.000Z","updated_at":"2024-02-23T12:20:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"577c0868-ec52-4f06-9c38-aef70c26e3fd","html_url":"https://github.com/zachgrayio/swift-tensorflow-starter","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zachgrayio%2Fswift-tensorflow-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zachgrayio%2Fswift-tensorflow-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zachgrayio%2Fswift-tensorflow-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zachgrayio%2Fswift-tensorflow-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zachgrayio","download_url":"https://codeload.github.com/zachgrayio/swift-tensorflow-starter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248131468,"owners_count":21052819,"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","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":["docker","starter-project","swift","swift-4","swift-for-tensorflow","swiftpm","tensorflow"],"created_at":"2024-09-24T20:38:14.065Z","updated_at":"2025-04-09T23:40:54.753Z","avatar_url":"https://github.com/zachgrayio.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/logo.png\"\u003e\n  \u003cbr /\u003e\n  \u003cbr /\u003e\n  An opinionated Swift for TensorFlow starter project.\n  \u003cbr /\u003e\n  \u003cbr /\u003e\n\u003c/p\u003e\n\n\n# Overview\n\nSTS is a [Docker](http://docker.com/)ized, [Swift Package Manager](https://swift.org/package-manager/) enabled starter repository for [Swift for TensorFlow](https://github.com/tensorflow/swift) projects. Now with hot-reload of Swift code and third-party packages!\n\n### Swift for TensorFlow\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/swift-tf-logo.png\"\u003e\n\u003c/p\u003e\n\nFrom the [official docs](https://github.com/tensorflow/swift):\n\n\u003eSwift for TensorFlow is a new way to develop machine learning models. It gives you the power of [TensorFlow](https://www.tensorflow.org) directly integrated into the [Swift programming language](https://swift.org/about).\n\n#### Disclaimer\n\n\u003e Note: Swift for TensorFlow is an early stage research project. It has been released to enable open source development and is not yet ready for general use by machine learning developers.\n\n### Architecture\n\nProjects built with this template will have the following traits:\n\n1. Build output is a deployable Docker image with an entrypoint to a release-built executable\n2. Quick and easy [REPL](https://github.com/tensorflow/swift/blob/master/Usage.md#repl-read-eval-print-loop) access against the project's Swift for Tensorflow code and third-party libraries\n3. Easily unit testable\n4. Runs anywhere Docker is available with no additional setup necessary - zero conflicts with existing Swift or TensorFlow installations.\n5. *Swift code is hot-reloaded on change; third-party libraries are downloaded automatically as well. See the `--live` flag.*\n\nThis will enable both ease of use during the research phase and a rapid transition to a scalable training solution and beyond (production deployment).\n\n### Docker\n\nThe project is fully Dockerized via the [swift-tensorflow](https://github.com/zachgrayio/swift-tensorflow) image, meaning you don't need to worry about setting up local dependencies or conflicts with existing Xcode/Swift installations when developing Swift+TF applications unless you really want to - all build/run tasks can be accomplished from within the container.\n\nMore information on the base docker image and avanced usage examples can be found in its [README](https://github.com/zachgrayio/swift-tensorflow/blob/master/README.md).\n\n* Note: The initial Docker build may take some time; Docker needs to download intermediate layers for the Ubuntu16 image if you haven't used it previously. However, subsequent builds should complete in under 10 seconds on a reasonable machine.*\n\n### Swift Package Manager\n\nThis project template is a [Swift Package Manager](https://swift.org/package-manager/) project - `Package.swift` defines the runnable application, the core library, and third-party dependencies.\n\n# Quickstart\n\n### Prerequisites\n\n#### Install Docker CE\n\nInstallation guides for macOS/Windows/Linux can be found [here](https://docs.docker.com/install/).\n\n#### Clone the `swift-tensorflow-starter` Repository\n\n```bash\ngit clone --depth 1 https://github.com/zachgrayio/swift-tensorflow-starter.git\ncd swift-tensorflow-starter\n```\n\nOptionally, you may reset `git` so you can commit and push to your own repository:\n\n```bash\nrm -rf .git\ngit init \u0026\u0026 git commit -am \"initial\"\n```\n\n## The Easy Way\n\nUsers on macOS and Linux can take advantage of the supplied run script for easy usage - no Docker expertise required!\n\n### 1) Build and Run with Hot Reload enabled\n\nAfter cloning, you can start the project in a single command using the `sts` executable that's included:\n\n```bash\n./sts run app --build --live\n```\n\nAfter this, any changes you make to the project will result in the Swift code being rebuilt in the container and the executable started. You can exit with `CTRL+C`.\n\n### 2) Add your Swift TensorFlow code\n\n* Add your Swift source files to the to `Sources/STSLibary` directory\n* If you'd like them to be part of the runnable application, add the appropriate calls to the `run()` method of `Application.swift`. Assuming you wire up valid code, you'll see your output.\n* If you'd rather just run the REPL, `CTRL-C` out of this session and run `./sts run repl --build`\n\nThat's it! However, it's recommended to continue reading and learn more about the underlying Docker container.\n\n## The Other Way\n\nThe following 4 steps describe how to add your code, build, and run the project with nothing other than the Docker binary; this should be relatively accurate cross-platform.\n\n### 1) Add your Swift TensorFlow code\n\n* Add your Swift source files to the to `Sources/STSLibary` directory\n* If you'd like them to be part of the runnable application, add the appropriate calls to the `run()` method of `Application.swift`. If you only want to access this code from the REPL, no further work is required now.\n\n### 2) Build\n\nDebug: \n\n```bash\ndocker build -t sts-application .\n```\n\nRelease: \n\n```bash\ndocker build --build-arg CONFIG=release -t sts-application .\n```\n\n*Note: you may tag your built container as anything you'd like; if you use a different tag, be sure to use it instead of `sts-application` in the following bash commands.*\n\n### 3) Run Unit Tests\n\n```bash\ndocker run --rm --entrypoint \"/usr/bin/swift\" sts-application test\n```\n\n### 4) Run\n\nNow you can either run the executable, or a REPL.\n\n#### Run the executable\n\n```bash\ndocker run --rm sts-application\n...\nSTS: [1.44, 0.64]\n```\n\n#### Run a REPL with access to the library\n\n```bash\ndocker run --rm --security-opt seccomp:unconfined -it \\\n    --entrypoint /usr/bin/swift \\\n    sts-application \\\n    -I/usr/lib/swift/clang/include \\\n    -I/usr/lib \\\n    -L/usr/lib \\\n    -lSTSLibrary \\\n    -lswiftPython \\\n    -lswiftTensorFlow\n```\n\nNow you can import anything defined in the `STSLibrary` module and interact with it. In this case, we're running the application.\n\n```\nWelcome to Swift version 4.2-dev (LLVM 04bdb56f3d, Clang b44dbbdf44). Type :help for assistance.\n  1\u003e import STSLibrary\n  2\u003e let app = Application()\napp: STSLibrary.Application = {}\n  3\u003e app.run()\nSTS: [1.44, 0.64]\n  4\u003e :exit\n```\n\n### Control Script\n\nA control script is included for extra convenience for users on macOS/Linux, but the Docker commands shown in steps 1-4 above also work on Windows.\n\nSome example commands:\n\n* `./sts run app --live` - automatically rebuild and run the application on code change; packages are updated automatically as well!\n* `./sts build --release`,  `./sts build -r`,   `./sts build -p`,   `./sts build --prod` - build the image with a release executable\n* `./sts run repl --build --name myrepl -v` - run a REPL in a container named myrepl, mounting the current directory as a volume, building the project first\n* `./sts run test`,  `./sts run tests --name testcontainer` - run unit tests\n* `./sts run xcode` - generate and opens a new xcode project\n* `./sts run app -b` - run the application, building the container first\n* `./sts run app -v` - runs an app tagged `myapp` with the current directory mounted as a volume to `/usr/src`.\n* `./sts run app -n mycontainer -b` - build and tag the current image `mycontainer` and then run it.\n\nNOTE: if you don't include the `-b|--build` flag to `app run` then the previously built image with that tag/name will be started. If an image with this tag is not found, one will be built.\n\n# Usage\n\n### Writing TensorFlow Code\n\nSomething to keep in mind when writing your TensorFlow code, as to avoid issues with send/receive (from the [official FAQ](https://github.com/tensorflow/swift/blob/master/FAQ.md#why-do-i-get-error-internal-error-generating-tensorflow-graph-graphgen-cannot-lower-a-sendreceive-to-the-host-yet)):\n\n\u003eWe recommend separating functions that do tensor computation from host code in your programs. Those functions should be marked as `@inline(never)` (and have `public` access, to be safe). Within those functions, tensor computation should not be interrupted by host code. This ensures that the arguments and results of the extracted tensor program will be values on the host, as expected.\n\n### SwiftPM Project Settings\n\nBy default the following names are used:\n\n* Executable: `STSApplication`\n* Library: `STSLibrary`\n* SwiftPM project: `STSProject`\n\nIf desired, you can easily override these values with a simple find/replace in the root directory. The files which need changes are `Package.swift` and the `Dockerfile`, the example test classes and run scripts, and a few directory names in `Sources` and `Tests`.\n\n### Third-party Libraries\n\nThird-party Swift libraries can be added to the `dependencies` collection in `Package.swift` and then imported for use. \n\nExample: \n\n```swift\n...\ndependencies: [\n    .package(url: \"https://github.com/ReactiveX/RxSwift.git\", \"4.0.0\" ..\u003c \"5.0.0\")\n],\n...\n```\n\n### System Dependencies\n\nThe project's `Dockerfile` is based on Ubuntu 16, so you can simply add `RUN apt-get install -y ...` entries to fetch additional dependencies.\n\n### Writing Unit Tests\n\nSee `STSLibraryTests.testApplicationPrefix()` in `Tests/STSLibraryTests/STSLibraryTests.swift` for an example test.\n\n*Note: TensorFlow is not yet supported in Unit Tests.*\n\n### Generate .xcodeproj\n\nIf desired, users on macOS can generate a `.xcodeproj` that you can open with an IDE (Xcode, AppCode, CLion). This is optional, and the xcodeproj is ignored in `.gitignore` by default. Also note that you'll want to swap out your xctoolchain as described [here](https://github.com/tensorflow/swift/blob/master/Installation.md) if you go this route.\n\nThe following command mounts a volume in the current directory and generates the project, resulting in the file being written to your host's disk.\n\n```bash\ndocker run --rm -v ${PWD}:/usr/src \\\n    --entrypoint /usr/bin/swift \\\n    sts-application \\\n    package generate-xcodeproj\nopen STSProject.xcodeproj\n```\n\n*Note: You can also run the `run_xcode.sh` script to generate and open the project.*\n\n### Examples\n\n* Using RxSwift: [[View Diff](https://github.com/zachgrayio/swift-tensorflow-starter/commit/cde51c28c608d9e08f460944eae836881fef47d9)]\n* Serving TensorFlow models with HTTP: coming soon.\n* Training TensorFlow models over HTTP: coming soon.\n\n### Leaving the Container\n\nIf you wish to run `swift build` and `swift run` on your project outside of the docker conainer, this is possible.\n\n* On Linux: you've got this.\n* On macOS: ensure you've [installed](https://github.com/tensorflow/swift/blob/master/Installation.md) the Swift for TensorFlow toolchain, and then use the following commands from within the project directory:\n\n```bash\nexport PATH=/Library/Developer/Toolchains/swift-latest/usr/bin:\"${PATH}\"\nswift run -Xswiftc -O\n```\n\n# License\n\nThis project is [MIT Licensed](https://github.com/zachgrayio/swift-tensorflow-starter/blob/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzachgrayio%2Fswift-tensorflow-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzachgrayio%2Fswift-tensorflow-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzachgrayio%2Fswift-tensorflow-starter/lists"}