Querying perplexity using sonar-pro for: cursor-tools installation guide with maxTokens: 8000
Here's a comprehensive guide on how to install and set up cursor-tools:

## Installation

To install cursor-tools, follow these steps:

1. Ensure you have Node.js 18 or later installed on your system[4].

2. Run the interactive setup command:

```bash
npx cursor-tools@latest install .
```

This command will[4]:
- Add `cursor-tools` as a dev dependency in your package.json
- Guide you through API key configuration
- Update your Cursor project rules for integration

## Requirements

Before installation, make sure you have the following[4]:

- Node.js 18 or later
- Perplexity API key
- Google Gemini API key
- For browser commands:
  - Playwright (`npm install --global playwright`)
  - OpenAI API key or Anthropic API key (for `act`, `extract`, and `observe` commands)

## API Key Configuration

During the installation process, you'll be prompted to enter your API keys[4]. These will be stored in a `.cursor-tools.env` file.

## Cursor Integration

cursor-tools automatically configures Cursor by updating your project rules during installation[4]. This provides:

- Command suggestions
- Usage examples
- Context-aware assistance

For new installations, it uses the `.cursor/rules/cursor-tools.mdc` file. For existing installations, it maintains compatibility with the legacy `.cursorrules` file[4].

## Cursor Agent Configuration

To get the full benefits of cursor-tools, use Cursor agent in "yolo mode"[4]. This allows the agent to execute commands directly.

## Usage

After installation, you can use cursor-tools in your projects. Here are some example commands:

1. Web search:
```bash
cursor-tools web "your query"
```

2. Repository search:
```bash
cursor-tools repo "your query"
```

3. Generate documentation:
```bash
cursor-tools doc "repository_url" "output_file.md"
```

4. GitHub integration:
```bash
cursor-tools github "fetch issue 123"
```

5. Browser automation:
```bash
cursor-tools browser open "https://example.com"
```

## Troubleshooting

If you encounter issues during installation or usage:

1. Ensure `cursor-tools` is properly installed and in your PATH[4].
2. Verify that the `.cursor-tools.env` file exists and contains valid API keys[4].
3. For GitHub operations, ensure your token has the required scopes (repo, read:user)[4].
4. Check your internet connection and API key permissions for model-related errors[4].

Remember, you can always run `cursor-tools install` again to reconfigure API keys or update your Cursor project rules[4].

By following this guide, you should be able to successfully install and set up cursor-tools for use with your Cursor AI editor.

web-results.md


Querying perplexity using sonar-pro for: go to https://ui.shadcn.com/docs and extract detailed setup instructions for a new project, including installation steps, configuration, and initial setup. Focus on the getting started and installation sections. with maxTokens: 8000

local-research/shadcn-ui-setup.md

Give Cursor Agent an AI Team and Advanced Skills


# Contribution to Ryujinx

You can contribute to Ryujinx with PRs, testing of PRs and issues. Contributing code and other implementations is greatly appreciated alongside simply filing issues for problems you encounter.
Please read the entire document before continuing as it can potentially save everyone involved a significant amount of time.

# Quick Links

* [Code Style Documentation](docs/coding-guidelines/coding-style.md)
* [Pull Request Guidelines](docs/workflow/pr-guide.md)

## Reporting Issues

We always welcome bug reports, feature proposals and overall feedback. Here are a few tips on how you can make reporting your issue as effective as possible.

### Identify Where to Report

The Ryujinx codebase is distributed across multiple repositories in the [Ryujinx organization](https://github.com/ryujinx-mirror). Depending on the feedback you might want to file the issue on a different repo. Here are a few common repos:

* [Ryujinx/Ryujinx](https://github.com/ryujinx-mirror/Ryujinx) Ryujinx core project files.
* [Ryujinx/Ryujinx-Games-List](https://github.com/ryujinx-mirror/Ryujinx-Games-List) Ryujinx game compatibility list.
* [Ryujinx/Ryujinx-Website](https://github.com/ryujinx-mirror/Ryujinx-Website) Ryujinx website source code.
* [Ryujinx/Ryujinx-Ldn-Website](https://github.com/ryujinx-mirror/Ryujinx-Ldn-Website) Ryujinx LDN website source code.

### Finding Existing Issues

Before filing a new issue, please search our [open issues](https://github.com/ryujinx-mirror/Ryujinx/issues) to check if it already exists.

If you do find an existing issue, please include your own feedback in the discussion. Do consider upvoting (👍 reaction) the original post, as this helps us prioritize popular issues in our backlog.

### Writing a Good Feature Request

Please review any feature requests already opened to both check it has not already been suggested, and to familiarize yourself with the format. When ready to submit a proposal, please use the [Feature Request issue template](https://github.com/ryujinx-mirror/Ryujinx/issues/new?assignees=&labels=&projects=&template=feature_request.yml&title=%5BFeature+Request%5D).

### Writing a Good Bug Report

Good bug reports make it easier for maintainers to verify and root cause the underlying problem. The better a bug report, the faster the problem will be resolved.
Ideally, a bug report should contain the following information:

* A high-level description of the problem.
* A _minimal reproduction_, i.e. the smallest time commitment/configuration required to reproduce the wrong behavior. This can be in the form of a small homebrew application, or by providing a save file and reproduction steps for a specific game.
* A description of the _expected behavior_, contrasted with the _actual behavior_ observed.
* Information on the environment: OS/distro, CPU, GPU (including driver), RAM etc.
* A Ryujinx log file of the run instance where the issue occurred. Log files can be found in `[Executable Folder]/Logs` and are named chronologically.
* Additional information, e.g. is it a regression from previous versions? Are there any known workarounds?

When ready to submit a bug report, please use the [Bug Report issue template](https://github.com/ryujinx-mirror/Ryujinx/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D).

## Contributing Changes

Project maintainers will merge changes that both improve the project and meet our standards for code quality.

The [Pull Request Guide](docs/workflow/pr-guide.md) and [License](https://github.com/ryujinx-mirror/Ryujinx/blob/master/LICENSE.txt) docs define additional guidance.

### DOs and DON'Ts

Please do:

* **DO** follow our [coding style](docs/coding-guidelines/coding-style.md) (C# code-specific).
* **DO** give priority to the current style of the project or file you're changing even if it diverges from the general guidelines.
* **DO** keep the discussions focused. When a new or related topic comes up
  it's often better to create new issue than to side track the discussion.
* **DO** clearly state on an issue that you are going to take on implementing it.
* **DO** blog and tweet (or whatever) about your contributions, frequently!

Please do not:

* **DON'T** make PRs for style changes.
* **DON'T** surprise us with big pull requests. Instead, file an issue and talk with us on Discord to start
  a discussion so we can agree on a direction before you invest a large amount
  of time.
* **DON'T** commit code that you didn't write. If you find code that you think is a good fit to add to Ryujinx, file an issue or talk to us on Discord to start a discussion before proceeding.
* **DON'T** submit PRs that alter licensing related files or headers. If you believe there's a problem with them, file an issue and we'll be happy to discuss it.

### Suggested Workflow

We use and recommend the following workflow:

1. Create or find an issue for your work.
    - You can skip this step for trivial changes.
    - Get agreement from the team and the community that your proposed change is a good one if it is of significant size or changes core functionality.
    - Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person.
2. Create a personal fork of the repository on GitHub (if you don't already have one).
3. In your fork, create a branch off of main (`git checkout -b mybranch`).
    - Branches are useful since they isolate your changes from incoming changes from upstream. They also enable you to create multiple PRs from the same fork.
4. Make and commit your changes to your branch.
    - [Build Instructions](https://github.com/ryujinx-mirror/Ryujinx#building) explains how to build and test.
    - Commit messages should be clear statements of action and intent.
6. Build the repository with your changes.
    - Make sure that the builds are clean.
    - Make sure that `dotnet format` has been run and any corrections tested and committed.
7. Create a pull request (PR) against the Ryujinx/Ryujinx repository's **main** branch.
    - State in the description what issue or improvement your change is addressing.
    - Check if all the Continuous Integration checks are passing. Refer to [Actions](https://github.com/ryujinx-mirror/Ryujinx/actions) to check for outstanding errors.
8. Wait for feedback or approval of your changes from the [core development team](https://github.com/orgs/Ryujinx/teams/developers)
    - Details about the pull request [review procedure](docs/workflow/ci/pr-guide.md).
9. When the team members have signed off, and all checks are green, your PR will be merged.
    - The next official build will automatically include your change.
    - You can delete the branch you used for making the change.

### Good First Issues

The team marks the most straightforward issues as [good first issues](https://github.com/ryujinx-mirror/Ryujinx/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). This set of issues is the place to start if you are interested in contributing but new to the codebase.

### Commit Messages

Please format commit messages as follows (based on [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)):

```
Summarize change in 50 characters or less

Provide more detail after the first line. Leave one blank line below the
summary and wrap all lines at 72 characters or less.

If the change fixes an issue, leave another blank line after the final
paragraph and indicate which issue is fixed in the specific format
below.

Fix #42
```

Also do your best to factor commits appropriately, not too large with unrelated things in the same commit, and not too small with the same small change applied N times in N different commits.

### PR - CI Process

The [Ryujinx continuous integration](https://github.com/ryujinx-mirror/Ryujinx/actions) (CI) system will automatically perform the required builds and run tests (including the ones you are expected to run) for PRs. Builds and test runs must be clean or have bugs properly filed against flaky/unexpected failures that are unrelated to your change.

If the CI build fails for any reason, the PR actions tab should be consulted for further information on the failure. There are a few usual suspects for such a failure:
* `dotnet format` has not been run on the PR and has outstanding stylistic issues.
* There is an error within the PR that fails a test or errors the compiler.
* Random failure of the workflow can occasionally result in a CI failure. In this scenario a maintainer will manually restart the job.

### PR Feedback

Ryujinx team and community members will provide feedback on your change. Community feedback is highly valued. You may see the absence of team feedback if the community has already provided good review feedback.

Two Ryujinx team members must review and approve every PR prior to merge. They will often reply with "LGTM, see nit". That means that the PR will be merged once the feedback is resolved. "LGTM" == "looks good to me".

There are lots of thoughts and [approaches](https://github.com/antlr/antlr4-cpp/blob/master/CONTRIBUTING.md#emoji) for how to efficiently discuss changes. It is best to be clear and explicit with your feedback. Please be patient with people who might not understand the finer details about your approach to feedback.

#### Copying Changes from Other Projects

Ryujinx uses some implementations and frameworks from other projects. The following rules must be followed for PRs that include changes from another project:

- The license of the file is [permissive](https://en.wikipedia.org/wiki/Permissive_free_software_licence).
- The license of the file is left in-tact.
- The contribution is correctly attributed in the [3rd party notices](https://github.com/ryujinx-mirror/Ryujinx/blob/master/distribution/legal/THIRDPARTY.md) file in the repository, as needed.

CONTRIBUTING.md

Hard-fork of the Ryujinx project


[links/discord]: https://discord.gg/xmHPGDfVCa
[badges/discord]: https://img.shields.io/discord/1291765437100720243?label=ryujinx-mirror&logo=discord&logoColor=FFFFFF&color=5865F3

As of now, the [ryujinx-mirror/ryujinx](https://github.com/ryujinx-mirror/ryujinx) repository serves as a downstream hard fork of the original Ryujinx project. You can download nightly binaries for Windows, macOS, and Linux (including `AppImage`s) from the [latest release](https://github.com/ryujinx-mirror/ryujinx/releases/latest).

> [!NOTE]
> This fork is not affiliated with the **original** Ryujinx project, or Nintendo whatsoever.

### Current Goals

If you would like a version with more new features & improvements, feel free to check out [GreemDev's fork](https://github.com/GreemDev/Ryujinx). We aim to keep this repository more focused on small fixes and infrastructure reconstruction, staying more true to the original Ryujinx project.

* ☑ Reconstruct basic build infrastructure & workflows for this repository, based on revision hashes as opposed to semver releases (for now)
* ☑ To be as safe as possible, remove all previous in-app and meta references to Patreon, `ryujinx.org` etc while keeping full attribution of original authors and contributors in-tact.
* Keep 'branding' as pure and faithful to the original project as possible.

### Join Discussion

Feel free to join the [ryujinx-mirror Discord community][links/discord] to join in on the development of this fork going forward.

See `#ryujinx-info` for more information.

[![ryujinx-mirror Discord][badges/discord]][links/discord]

___

  Ryujinx

  (REE-YOU-JINX)

  Ryujinx is an open-source Nintendo Switch emulator, created by gdkchan, written in C#.
  This emulator aims at providing excellent accuracy and performance, a user-friendly interface and consistent builds.
  It was written from scratch and development on the project began in September 2017.
  Ryujinx is available on Github under the MIT license.

## Compatibility

As of May 2024, Ryujinx has been tested on approximately 4,300 titles;
over 4,100 boot past menus and into gameplay, with roughly 3,550 of those being considered playable.

You can check out the compatibility list [here](https://github.com/ryujinx-mirror/Ryujinx-Games-List/issues).

Anyone is free to submit a new game test or update an existing game test entry;
simply follow the new issue template and testing guidelines, or post as a reply to the applicable game issue.
Use the search function to see if a game has been tested already!

## Usage

To run this emulator, your PC must be equipped with at least 8GiB of RAM;
failing to meet this requirement may result in a poor gameplay experience or unexpected crashes.

## Latest build

These builds are compiled automatically for each commit on the master branch.
While we strive to ensure optimal stability and performance prior to pushing an update, our automated builds **may be unstable or completely broken**.

See [the releases page](https://github.com/ryujinx-mirror/ryujinx/releases) for automatic builds for Windows, macOS, and Linux.

## Documentation

If you are planning to contribute or just want to learn more about this project please read through our [documentation](docs/README.md).

## Building

If you wish to build the emulator yourself, follow these steps:

### Step 1

Install the [.NET 8.0 (or higher) SDK](https://dotnet.microsoft.com/download/dotnet/8.0).
Make sure your SDK version is higher or equal to the required version specified in [global.json](global.json).

### Step 2

Either use `git clone https://github.com/ryujinx-mirror/ryujinx` on the command line to clone the repository or use Code --> Download zip button to get the files.

### Step 3

To build Ryujinx, open a command prompt inside the project directory.
You can quickly access it on Windows by holding shift in File Explorer, then right clicking and selecting `Open command window here`.
Then type the following command: `dotnet build -c Release -o build`
the built files will be found in the newly created build directory.

Ryujinx system files are stored in the `Ryujinx` folder.
This folder is located in the user folder, which can be accessed by clicking `Open Ryujinx Folder` under the File menu in the GUI.

## Features

- **Audio**

  Audio output is entirely supported, audio input (microphone) isn't supported.
  We use C# wrappers for [OpenAL](https://openal-soft.org/), and [SDL2](https://www.libsdl.org/) & [libsoundio](http://libsound.io/) as fallbacks.

- **CPU**

  The CPU emulator, ARMeilleure, emulates an ARMv8 CPU and currently has support for most 64-bit ARMv8 and some of the ARMv7 (and older) instructions, including partial 32-bit support.
  It translates the ARM code to a custom IR, performs a few optimizations, and turns that into x86 code.
  There are three memory manager options available depending on the user's preference, leveraging both software-based (slower) and host-mapped modes (much faster).
  The fastest option (host, unchecked) is set by default.
  Ryujinx also features an optional Profiled Persistent Translation Cache, which essentially caches translated functions so that they do not need to be translated every time the game loads.
  The net result is a significant reduction in load times (the amount of time between launching a game and arriving at the title screen) for nearly every game.
  NOTE: This feature is enabled by default in the Options menu > System tab.
  You must launch the game at least twice to the title screen or beyond before performance improvements are unlocked on the third launch!
  These improvements are permanent and do not require any extra launches going forward.

- **GPU**

  The GPU emulator emulates the Switch's Maxwell GPU using either the OpenGL (version 4.5 minimum), Vulkan, or Metal (via MoltenVK) APIs through a custom build of OpenTK or Silk.NET respectively.
  There are currently six graphics enhancements available to the end user in Ryujinx: Disk Shader Caching, Resolution Scaling, Anti-Aliasing, Scaling Filters (including FSR), Anisotropic Filtering and Aspect Ratio Adjustment.
  These enhancements can be adjusted or toggled as desired in the GUI.

- **Input**

  We currently have support for keyboard, mouse, touch input, JoyCon input support, and nearly all controllers.
  Motion controls are natively supported in most cases; for dual-JoyCon motion support, DS4Windows or BetterJoy are currently required.
  In all scenarios, you can set up everything inside the input configuration menu.

- **DLC & Modifications**

  Ryujinx is able to manage add-on content/downloadable content through the GUI.
  Mods (romfs, exefs, and runtime mods such as cheats) are also supported;
  the GUI contains a shortcut to open the respective mods folder for a particular game.

- **Configuration**

  The emulator has settings for enabling or disabling some logging, remapping controllers, and more.
  You can configure all of them through the graphical interface or manually through the config file, `Config.json`, found in the user folder which can be accessed by clicking `Open Ryujinx Folder` under the File menu in the GUI.

## License

This software is licensed under the terms of the [MIT license](LICENSE.txt).
This project makes use of code authored by the libvpx project, licensed under BSD and the ffmpeg project, licensed under LGPLv3.
See [LICENSE.txt](LICENSE.txt) and [THIRDPARTY.md](distribution/legal/THIRDPARTY.md) for more details.

## Credits

- [LibHac](https://github.com/Thealexbarney/LibHac) is used for our file-system.
- [AmiiboAPI](https://www.amiiboapi.com) is used in our Amiibo emulation.
- [ldn_mitm](https://github.com/spacemeowx2/ldn_mitm) is used for one of our available multiplayer modes.
- [ShellLink](https://github.com/securifybv/ShellLink) is used for Windows shortcut generation.

README.md

Hard-fork of the Ryujinx project


# Documents Index

This repo includes several documents that explain both high-level and low-level concepts about Ryujinx and its functions. These are very useful for contributors, to get context that can be very difficult to acquire from just reading code.

Intro to Ryujinx
==================

Ryujinx is an open-source Nintendo Switch emulator, created by gdkchan, written in C#.
* The CPU emulator, ARMeilleure, emulates an ARMv8 CPU and currently has support for most 64-bit ARMv8 and some of the ARMv7 (and older) instructions.
* The GPU emulator emulates the Switch's Maxwell GPU using either the OpenGL (version 4.5 minimum), Vulkan, or Metal (via MoltenVK) APIs through a custom build of OpenTK or Silk.NET respectively.
* Audio output is entirely supported via C# wrappers for SDL2, with OpenAL & libsoundio as fallbacks.

Getting Started
===============

- [Installing the .NET SDK](https://dotnet.microsoft.com/download)
- [Official .NET Docs](https://docs.microsoft.com/dotnet/core/)

Contributing (Building, testing, benchmarking, profiling, etc.)
===============

If you want to contribute a code change to this repo, start here.

- [Contributor Guide](../CONTRIBUTING.md)

Coding Guidelines
=================

- [C# coding style](coding-guidelines/coding-style.md)
- [Service Implementation Guidelines - WIP](https://gist.github.com/gdkchan/84ba88cd50efbe58d1babfaa7cd7c455)

Project Docs
=================

To be added. Many project files will contain basic XML docs for key functions and classes in the meantime.

docs/README.md

Hard-fork of the Ryujinx project


# ffmpeg (LGPLv3)

  See License

  ```
                     GNU LESSER GENERAL PUBLIC LICENSE
                         Version 3, 29 June 2007

   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

    This version of the GNU Lesser General Public License incorporates
  the terms and conditions of version 3 of the GNU General Public
  License, supplemented by the additional permissions listed below.

    0. Additional Definitions.

    As used herein, "this License" refers to version 3 of the GNU Lesser
  General Public License, and the "GNU GPL" refers to version 3 of the GNU
  General Public License.

    "The Library" refers to a covered work governed by this License,
  other than an Application or a Combined Work as defined below.

    An "Application" is any work that makes use of an interface provided
  by the Library, but which is not otherwise based on the Library.
  Defining a subclass of a class defined by the Library is deemed a mode
  of using an interface provided by the Library.

    A "Combined Work" is a work produced by combining or linking an
  Application with the Library.  The particular version of the Library
  with which the Combined Work was made is also called the "Linked
  Version".

    The "Minimal Corresponding Source" for a Combined Work means the
  Corresponding Source for the Combined Work, excluding any source code
  for portions of the Combined Work that, considered in isolation, are
  based on the Application, and not on the Linked Version.

    The "Corresponding Application Code" for a Combined Work means the
  object code and/or source code for the Application, including any data
  and utility programs needed for reproducing the Combined Work from the
  Application, but excluding the System Libraries of the Combined Work.

    1. Exception to Section 3 of the GNU GPL.

    You may convey a covered work under sections 3 and 4 of this License
  without being bound by section 3 of the GNU GPL.

    2. Conveying Modified Versions.

    If you modify a copy of the Library, and, in your modifications, a
  facility refers to a function or data to be supplied by an Application
  that uses the facility (other than as an argument passed when the
  facility is invoked), then you may convey a copy of the modified
  version:

     a) under this License, provided that you make a good faith effort to
     ensure that, in the event an Application does not supply the
     function or data, the facility still operates, and performs
     whatever part of its purpose remains meaningful, or

     b) under the GNU GPL, with none of the additional permissions of
     this License applicable to that copy.

    3. Object Code Incorporating Material from Library Header Files.

    The object code form of an Application may incorporate material from
  a header file that is part of the Library.  You may convey such object
  code under terms of your choice, provided that, if the incorporated
  material is not limited to numerical parameters, data structure
  layouts and accessors, or small macros, inline functions and templates
  (ten or fewer lines in length), you do both of the following:

     a) Give prominent notice with each copy of the object code that the
     Library is used in it and that the Library and its use are
     covered by this License.

     b) Accompany the object code with a copy of the GNU GPL and this license
     document.

    4. Combined Works.

    You may convey a Combined Work under terms of your choice that,
  taken together, effectively do not restrict modification of the
  portions of the Library contained in the Combined Work and reverse
  engineering for debugging such modifications, if you also do each of
  the following:

     a) Give prominent notice with each copy of the Combined Work that
     the Library is used in it and that the Library and its use are
     covered by this License.

     b) Accompany the Combined Work with a copy of the GNU GPL and this license
     document.

     c) For a Combined Work that displays copyright notices during
     execution, include the copyright notice for the Library among
     these notices, as well as a reference directing the user to the
     copies of the GNU GPL and this license document.

     d) Do one of the following:

         0) Convey the Minimal Corresponding Source under the terms of this
         License, and the Corresponding Application Code in a form
         suitable for, and under terms that permit, the user to
         recombine or relink the Application with a modified version of
         the Linked Version to produce a modified Combined Work, in the
         manner specified by section 6 of the GNU GPL for conveying
         Corresponding Source.

         1) Use a suitable shared library mechanism for linking with the
         Library.  A suitable mechanism is one that (a) uses at run time
         a copy of the Library already present on the user's computer
         system, and (b) will operate properly with a modified version
         of the Library that is interface-compatible with the Linked
         Version.

     e) Provide Installation Information, but only if you would otherwise
     be required to provide such information under section 6 of the
     GNU GPL, and only to the extent that such information is
     necessary to install and execute a modified version of the
     Combined Work produced by recombining or relinking the
     Application with a modified version of the Linked Version. (If
     you use option 4d0, the Installation Information must accompany
     the Minimal Corresponding Source and Corresponding Application
     Code. If you use option 4d1, you must provide the Installation
     Information in the manner specified by section 6 of the GNU GPL
     for conveying Corresponding Source.)

    5. Combined Libraries.

    You may place library facilities that are a work based on the
  Library side by side in a single library together with other library
  facilities that are not Applications and are not covered by this
  License, and convey such a combined library under terms of your
  choice, if you do both of the following:

     a) Accompany the combined library with a copy of the same work based
     on the Library, uncombined with any other library facilities,
     conveyed under the terms of this License.

     b) Give prominent notice with the combined library that part of it
     is a work based on the Library, and explaining where to find the
     accompanying uncombined form of the same work.

    6. Revised Versions of the GNU Lesser General Public License.

    The Free Software Foundation may publish revised and/or new versions
  of the GNU Lesser General Public License from time to time. Such new
  versions will be similar in spirit to the present version, but may
  differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the
  Library as you received it specifies that a certain numbered version
  of the GNU Lesser General Public License "or any later version"
  applies to it, you have the option of following the terms and
  conditions either of that published version or of any later version
  published by the Free Software Foundation. If the Library as you
  received it does not specify a version number of the GNU Lesser
  General Public License, you may choose any version of the GNU Lesser
  General Public License ever published by the Free Software Foundation.

    If the Library as you received it specifies that a proxy can decide
  whether future versions of the GNU Lesser General Public License shall
  apply, that proxy's public statement of acceptance of any version is
  permanent authorization for you to choose that version for the
  Library.
  ```

# libvpx (BSD)

  See License

  ```
  Copyright (c) 2010, The WebM Project authors. All rights reserved.

  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions are
  met:

    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.

    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in
      the documentation and/or other materials provided with the
      distribution.

    * Neither the name of Google, nor the WebM Project, nor the names
      of its contributors may be used to endorse or promote products
      derived from this software without specific prior written
      permission.

  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  ```

# Atmosphère (MIT)

  See License

  ```
  MIT License

  Copyright (c) 2018-2020 Atmosphère-NX

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to deal
  in the Software without restriction, including without limitation the rights
  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in all
  copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.
  ```

# OpenAL Soft (LGPLv2)

  See License

  ```
                    GNU LIBRARY GENERAL PUBLIC LICENSE
                         Version 2, June 1991

   Copyright (C) 1991 Free Software Foundation, Inc.
   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

  [This is the first released version of the library GPL.  It is
   numbered 2 because it goes with version 2 of the ordinary GPL.]

                              Preamble

    The licenses for most software are designed to take away your
  freedom to share and change it.  By contrast, the GNU General Public
  Licenses are intended to guarantee your freedom to share and change
  free software--to make sure the software is free for all its users.

    This license, the Library General Public License, applies to some
  specially designated Free Software Foundation software, and to any
  other libraries whose authors decide to use it.  You can use it for
  your libraries, too.

    When we speak of free software, we are referring to freedom, not
  price.  Our General Public Licenses are designed to make sure that you
  have the freedom to distribute copies of free software (and charge for
  this service if you wish), that you receive source code or can get it
  if you want it, that you can change the software or use pieces of it
  in new free programs; and that you know you can do these things.

    To protect your rights, we need to make restrictions that forbid
  anyone to deny you these rights or to ask you to surrender the rights.
  These restrictions translate to certain responsibilities for you if
  you distribute copies of the library, or if you modify it.

    For example, if you distribute copies of the library, whether gratis
  or for a fee, you must give the recipients all the rights that we gave
  you.  You must make sure that they, too, receive or can get the source
  code.  If you link a program with the library, you must provide
  complete object files to the recipients so that they can relink them
  with the library, after making changes to the library and recompiling
  it.  And you must show them these terms so they know their rights.

    Our method of protecting your rights has two steps: (1) copyright
  the library, and (2) offer you this license which gives you legal
  permission to copy, distribute and/or modify the library.

    Also, for each distributor's protection, we want to make certain
  that everyone understands that there is no warranty for this free
  library.  If the library is modified by someone else and passed on, we
  want its recipients to know that what they have is not the original
  version, so that any problems introduced by others will not reflect on
  the original authors' reputations.

    Finally, any free program is threatened constantly by software
  patents.  We wish to avoid the danger that companies distributing free
  software will individually obtain patent licenses, thus in effect
  transforming the program into proprietary software.  To prevent this,
  we have made it clear that any patent must be licensed for everyone's
  free use or not licensed at all.

    Most GNU software, including some libraries, is covered by the ordinary
  GNU General Public License, which was designed for utility programs.  This
  license, the GNU Library General Public License, applies to certain
  designated libraries.  This license is quite different from the ordinary
  one; be sure to read it in full, and don't assume that anything in it is
  the same as in the ordinary license.

    The reason we have a separate public license for some libraries is that
  they blur the distinction we usually make between modifying or adding to a
  program and simply using it.  Linking a program with a library, without
  changing the library, is in some sense simply using the library, and is
  analogous to running a utility program or application program.  However, in
  a textual and legal sense, the linked executable is a combined work, a
  derivative of the original library, and the ordinary General Public License
  treats it as such.

    Because of this blurred distinction, using the ordinary General
  Public License for libraries did not effectively promote software
  sharing, because most developers did not use the libraries.  We
  concluded that weaker conditions might promote sharing better.

    However, unrestricted linking of non-free programs would deprive the
  users of those programs of all benefit from the free status of the
  libraries themselves.  This Library General Public License is intended to
  permit developers of non-free programs to use free libraries, while
  preserving your freedom as a user of such programs to change the free
  libraries that are incorporated in them.  (We have not seen how to achieve
  this as regards changes in header files, but we have achieved it as regards
  changes in the actual functions of the Library.)  The hope is that this
  will lead to faster development of free libraries.

    The precise terms and conditions for copying, distribution and
  modification follow.  Pay close attention to the difference between a
  "work based on the library" and a "work that uses the library".  The
  former contains code derived from the library, while the latter only
  works together with the library.

    Note that it is possible for a library to be covered by the ordinary
  General Public License rather than by this special one.

                    GNU LIBRARY GENERAL PUBLIC LICENSE
     TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

    0. This License Agreement applies to any software library which
  contains a notice placed by the copyright holder or other authorized
  party saying it may be distributed under the terms of this Library
  General Public License (also called "this License").  Each licensee is
  addressed as "you".

    A "library" means a collection of software functions and/or data
  prepared so as to be conveniently linked with application programs
  (which use some of those functions and data) to form executables.

    The "Library", below, refers to any such software library or work
  which has been distributed under these terms.  A "work based on the
  Library" means either the Library or any derivative work under
  copyright law: that is to say, a work containing the Library or a
  portion of it, either verbatim or with modifications and/or translated
  straightforwardly into another language.  (Hereinafter, translation is
  included without limitation in the term "modification".)

    "Source code" for a work means the preferred form of the work for
  making modifications to it.  For a library, complete source code means
  all the source code for all modules it contains, plus any associated
  interface definition files, plus the scripts used to control compilation
  and installation of the library.

    Activities other than copying, distribution and modification are not
  covered by this License; they are outside its scope.  The act of
  running a program using the Library is not restricted, and output from
  such a program is covered only if its contents constitute a work based
  on the Library (independent of the use of the Library in a tool for
  writing it).  Whether that is true depends on what the Library does
  and what the program that uses the Library does.

    1. You may copy and distribute verbatim copies of the Library's
  complete source code as you receive it, in any medium, provided that
  you conspicuously and appropriately publish on each copy an
  appropriate copyright notice and disclaimer of warranty; keep intact
  all the notices that refer to this License and to the absence of any
  warranty; and distribute a copy of this License along with the
  Library.

    You may charge a fee for the physical act of transferring a copy,
  and you may at your option offer warranty protection in exchange for a
  fee.

    2. You may modify your copy or copies of the Library or any portion
  of it, thus forming a work based on the Library, and copy and
  distribute such modifications or work under the terms of Section 1
  above, provided that you also meet all of these conditions:

      a) The modified work must itself be a software library.

      b) You must cause the files modified to carry prominent notices
      stating that you changed the files and the date of any change.

      c) You must cause the whole of the work to be licensed at no
      charge to all third parties under the terms of this License.

      d) If a facility in the modified Library refers to a function or a
      table of data to be supplied by an application program that uses
      the facility, other than as an argument passed when the facility
      is invoked, then you must make a good faith effort to ensure that,
      in the event an application does not supply such function or
      table, the facility still operates, and performs whatever part of
      its purpose remains meaningful.

      (For example, a function in a library to compute square roots has
      a purpose that is entirely well-defined independent of the
      application.  Therefore, Subsection 2d requires that any
      application-supplied function or table used by this function must
      be optional: if the application does not supply it, the square
      root function must still compute square roots.)

  These requirements apply to the modified work as a whole.  If
  identifiable sections of that work are not derived from the Library,
  and can be reasonably considered independent and separate works in
  themselves, then this License, and its terms, do not apply to those
  sections when you distribute them as separate works.  But when you
  distribute the same sections as part of a whole which is a work based
  on the Library, the distribution of the whole must be on the terms of
  this License, whose permissions for other licensees extend to the
  entire whole, and thus to each and every part regardless of who wrote
  it.

  Thus, it is not the intent of this section to claim rights or contest
  your rights to work written entirely by you; rather, the intent is to
  exercise the right to control the distribution of derivative or
  collective works based on the Library.

  In addition, mere aggregation of another work not based on the Library
  with the Library (or with a work based on the Library) on a volume of
  a storage or distribution medium does not bring the other work under
  the scope of this License.

    3. You may opt to apply the terms of the ordinary GNU General Public
  License instead of this License to a given copy of the Library.  To do
  this, you must alter all the notices that refer to this License, so
  that they refer to the ordinary GNU General Public License, version 2,
  instead of to this License.  (If a newer version than version 2 of the
  ordinary GNU General Public License has appeared, then you can specify
  that version instead if you wish.)  Do not make any other change in
  these notices.

    Once this change is made in a given copy, it is irreversible for
  that copy, so the ordinary GNU General Public License applies to all
  subsequent copies and derivative works made from that copy.

    This option is useful when you wish to copy part of the code of
  the Library into a program that is not a library.

    4. You may copy and distribute the Library (or a portion or
  derivative of it, under Section 2) in object code or executable form
  under the terms of Sections 1 and 2 above provided that you accompany
  it with the complete corresponding machine-readable source code, which
  must be distributed under the terms of Sections 1 and 2 above on a
  medium customarily used for software interchange.

    If distribution of object code is made by offering access to copy
  from a designated place, then offering equivalent access to copy the
  source code from the same place satisfies the requirement to
  distribute the source code, even though third parties are not
  compelled to copy the source along with the object code.

    5. A program that contains no derivative of any portion of the
  Library, but is designed to work with the Library by being compiled or
  linked with it, is called a "work that uses the Library".  Such a
  work, in isolation, is not a derivative work of the Library, and
  therefore falls outside the scope of this License.

    However, linking a "work that uses the Library" with the Library
  creates an executable that is a derivative of the Library (because it
  contains portions of the Library), rather than a "work that uses the
  library".  The executable is therefore covered by this License.
  Section 6 states terms for distribution of such executables.

    When a "work that uses the Library" uses material from a header file
  that is part of the Library, the object code for the work may be a
  derivative work of the Library even though the source code is not.
  Whether this is true is especially significant if the work can be
  linked without the Library, or if the work is itself a library.  The
  threshold for this to be true is not precisely defined by law.

    If such an object file uses only numerical parameters, data
  structure layouts and accessors, and small macros and small inline
  functions (ten lines or less in length), then the use of the object
  file is unrestricted, regardless of whether it is legally a derivative
  work.  (Executables containing this object code plus portions of the
  Library will still fall under Section 6.)

    Otherwise, if the work is a derivative of the Library, you may
  distribute the object code for the work under the terms of Section 6.
  Any executables containing that work also fall under Section 6,
  whether or not they are linked directly with the Library itself.

    6. As an exception to the Sections above, you may also compile or
  link a "work that uses the Library" with the Library to produce a
  work containing portions of the Library, and distribute that work
  under terms of your choice, provided that the terms permit
  modification of the work for the customer's own use and reverse
  engineering for debugging such modifications.

    You must give prominent notice with each copy of the work that the
  Library is used in it and that the Library and its use are covered by
  this License.  You must supply a copy of this License.  If the work
  during execution displays copyright notices, you must include the
  copyright notice for the Library among them, as well as a reference
  directing the user to the copy of this License.  Also, you must do one
  of these things:

      a) Accompany the work with the complete corresponding
      machine-readable source code for the Library including whatever
      changes were used in the work (which must be distributed under
      Sections 1 and 2 above); and, if the work is an executable linked
      with the Library, with the complete machine-readable "work that
      uses the Library", as object code and/or source code, so that the
      user can modify the Library and then relink to produce a modified
      executable containing the modified Library.  (It is understood
      that the user who changes the contents of definitions files in the
      Library will not necessarily be able to recompile the application
      to use the modified definitions.)

      b) Accompany the work with a written offer, valid for at
      least three years, to give the same user the materials
      specified in Subsection 6a, above, for a charge no more
      than the cost of performing this distribution.

      c) If distribution of the work is made by offering access to copy
      from a designated place, offer equivalent access to copy the above
      specified materials from the same place.

      d) Verify that the user has already received a copy of these
      materials or that you have already sent this user a copy.

    For an executable, the required form of the "work that uses the
  Library" must include any data and utility programs needed for
  reproducing the executable from it.  However, as a special exception,
  the source code distributed need not include anything that is normally
  distributed (in either source or binary form) with the major
  components (compiler, kernel, and so on) of the operating system on
  which the executable runs, unless that component itself accompanies
  the executable.

    It may happen that this requirement contradicts the license
  restrictions of other proprietary libraries that do not normally
  accompany the operating system.  Such a contradiction means you cannot
  use both them and the Library together in an executable that you
  distribute.

    7. You may place library facilities that are a work based on the
  Library side-by-side in a single library together with other library
  facilities not covered by this License, and distribute such a combined
  library, provided that the separate distribution of the work based on
  the Library and of the other library facilities is otherwise
  permitted, and provided that you do these two things:

      a) Accompany the combined library with a copy of the same work
      based on the Library, uncombined with any other library
      facilities.  This must be distributed under the terms of the
      Sections above.

      b) Give prominent notice with the combined library of the fact
      that part of it is a work based on the Library, and explaining
      where to find the accompanying uncombined form of the same work.

    8. You may not copy, modify, sublicense, link with, or distribute
  the Library except as expressly provided under this License.  Any
  attempt otherwise to copy, modify, sublicense, link with, or
  distribute the Library is void, and will automatically terminate your
  rights under this License.  However, parties who have received copies,
  or rights, from you under this License will not have their licenses
  terminated so long as such parties remain in full compliance.

    9. You are not required to accept this License, since you have not
  signed it.  However, nothing else grants you permission to modify or
  distribute the Library or its derivative works.  These actions are
  prohibited by law if you do not accept this License.  Therefore, by
  modifying or distributing the Library (or any work based on the
  Library), you indicate your acceptance of this License to do so, and
  all its terms and conditions for copying, distributing or modifying
  the Library or works based on it.

    10. Each time you redistribute the Library (or any work based on the
  Library), the recipient automatically receives a license from the
  original licensor to copy, distribute, link with or modify the Library
  subject to these terms and conditions.  You may not impose any further
  restrictions on the recipients' exercise of the rights granted herein.
  You are not responsible for enforcing compliance by third parties to
  this License.

    11. If, as a consequence of a court judgment or allegation of patent
  infringement or for any other reason (not limited to patent issues),
  conditions are imposed on you (whether by court order, agreement or
  otherwise) that contradict the conditions of this License, they do not
  excuse you from the conditions of this License.  If you cannot
  distribute so as to satisfy simultaneously your obligations under this
  License and any other pertinent obligations, then as a consequence you
  may not distribute the Library at all.  For example, if a patent
  license would not permit royalty-free redistribution of the Library by
  all those who receive copies directly or indirectly through you, then
  the only way you could satisfy both it and this License would be to
  refrain entirely from distribution of the Library.

  If any portion of this section is held invalid or unenforceable under any
  particular circumstance, the balance of the section is intended to apply,
  and the section as a whole is intended to apply in other circumstances.

  It is not the purpose of this section to induce you to infringe any
  patents or other property right claims or to contest validity of any
  such claims; this section has the sole purpose of protecting the
  integrity of the free software distribution system which is
  implemented by public license practices.  Many people have made
  generous contributions to the wide range of software distributed
  through that system in reliance on consistent application of that
  system; it is up to the author/donor to decide if he or she is willing
  to distribute software through any other system and a licensee cannot
  impose that choice.

  This section is intended to make thoroughly clear what is believed to
  be a consequence of the rest of this License.

    12. If the distribution and/or use of the Library is restricted in
  certain countries either by patents or by copyrighted interfaces, the
  original copyright holder who places the Library under this License may add
  an explicit geographical distribution limitation excluding those countries,
  so that distribution is permitted only in or among countries not thus
  excluded.  In such case, this License incorporates the limitation as if
  written in the body of this License.

    13. The Free Software Foundation may publish revised and/or new
  versions of the Library General Public License from time to time.
  Such new versions will be similar in spirit to the present version,
  but may differ in detail to address new problems or concerns.

  Each version is given a distinguishing version number.  If the Library
  specifies a version number of this License which applies to it and
  "any later version", you have the option of following the terms and
  conditions either of that version or of any later version published by
  the Free Software Foundation.  If the Library does not specify a
  license version number, you may choose any version ever published by
  the Free Software Foundation.

    14. If you wish to incorporate parts of the Library into other free
  programs whose distribution conditions are incompatible with these,
  write to the author to ask for permission.  For software which is
  copyrighted by the Free Software Foundation, write to the Free
  Software Foundation; we sometimes make exceptions for this.  Our
  decision will be guided by the two goals of preserving the free status
  of all derivatives of our free software and of promoting the sharing
  and reuse of software generally.

                              NO WARRANTY

    15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
  WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
  OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
  KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
  LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
  THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

    16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
  WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
  AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
  FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
  CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
  LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
  RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
  FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
  SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
  DAMAGES.

                       END OF TERMS AND CONDITIONS
  ```
</details>

# ShellLink (MIT)
<details>
  <summary>See License</summary>

  ```
  MIT License

  Copyright (c) 2017 Yorick Koster, Securify B.V.

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to deal
  in the Software without restriction, including without limitation the rights
  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in all
  copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.
  ```

Hard-fork of the Ryujinx project


# C# Coding Style

The general rule we follow is "use Visual Studio defaults".
Using an IDE that supports the `.editorconfig` standard will make this much simpler.

1. We use [Allman style](http://en.wikipedia.org/wiki/Indent_style#Allman_style) braces, where each brace begins on a new line. A single line statement block can go without braces but the block must be properly indented on its own line and must not be nested in other statement blocks that use braces (See rule 18 for more details). One exception is that a `using` statement is permitted to be nested within another `using` statement by starting on the following line at the same indentation level, even if the nested `using` contains a controlled block.
2. We use four spaces of indentation (no tabs).
3. We use `_camelCase` for internal and private fields and use `readonly` where possible. Prefix internal and private instance fields with `_`, thread static fields with `t_`. When used on static fields, `readonly` should come after `static` (e.g. `static readonly` not `readonly static`).  Public fields should be used sparingly and should use PascalCasing with no prefix when used.
4. We avoid `this.` unless absolutely necessary.
5. We always specify the visibility, even if it's the default (e.g.
   `private string _foo` not `string _foo`). Visibility should be the first modifier (e.g.
   `public abstract` not `abstract public`).
6. Namespace imports should be specified at the top of the file, *outside* of `namespace` declarations.
7. Avoid more than one empty line at any time. For example, do not have two
   blank lines between members of a type.
8. Avoid spurious free spaces.
   For example avoid `if (someVar == 0)...`, where the dots mark the spurious free spaces.
   Consider enabling "View White Space (Ctrl+R, Ctrl+W)" or "Edit -> Advanced -> View White Space" if using Visual Studio to aid detection.
9. If a file happens to differ in style from these guidelines (e.g. private members are named `m_member`
   rather than `_member`), the existing style in that file takes precedence.
10. We only use `var` when the type is explicitly named on the right-hand side, typically due to either `new` or an explicit cast, e.g. `var stream = new FileStream(...)` not `var stream = OpenStandardInput()`.
    - Similarly, target-typed `new()` can only be used when the type is explicitly named on the left-hand side, in a variable definition statement or a field definition statement. e.g. `FileStream stream = new(...);`, but not `stream = new(...);` (where the type was specified on a previous line).
11. We use language keywords instead of BCL types (e.g. `int, string, float` instead of `Int32, String, Single`, etc) for both type references as well as method calls (e.g. `int.Parse` instead of `Int32.Parse`). See issue [#13976](https://github.com/dotnet/runtime/issues/13976) for examples.
12. We use PascalCasing to name all our constant local variables and fields. The only exception is for interop code where the constant value should exactly match the name and value of the code you are calling via interop.
13. We use PascalCasing for all method names, including local functions.
14. We use ```nameof(...)``` instead of ```"..."``` whenever possible and relevant.
15. Fields should be specified at the top within type declarations.
16. When including non-ASCII characters in the source code use Unicode escape sequences (\uXXXX) instead of literal characters. Literal non-ASCII characters occasionally get garbled by a tool or editor.
17. When using labels (for goto), indent the label one less than the current indentation.
18. When using a single-statement if, we follow these conventions:
    - Never use single-line form (for example: `if (source == null) throw new ArgumentNullException("source");`)
    - Using braces is always accepted, and required if any block of an `if`/`else if`/.../`else` compound statement uses braces or if a single statement body spans multiple lines.
    - Braces may be omitted only if the body of *every* block associated with an `if`/`else if`/.../`else` compound statement is placed on a single line.
19. Make all internal and private types static or sealed unless derivation from them is required.  As with any implementation detail, they can be changed if/when derivation is required in the future.
20. XML docs should be used when writing interfaces or when a class/method is deemed sufficient in scope or complexity.
21. So-called [Magic Numbers](https://en.wikipedia.org/wiki/Magic_number_(programming)) should be defined as named constants before use (for example `for (int i = 56; i < 68; i++)` could read `for (int i = _currentAge; i < _retireAge; i++)`).
    This may be ignored for trivial or syntactically common statements.

An [EditorConfig](https://editorconfig.org "EditorConfig homepage") file (`.editorconfig`) has been provided at the root of the runtime repository, enabling C# auto-formatting conforming to the above guidelines.

### Example File:

``ShaderCache.cs:``

```C#
using Ryujinx.Common.Configuration;
using Ryujinx.Common.Logging;
using Ryujinx.Graphics.GAL;
using Ryujinx.Graphics.Gpu.Engine.Threed;
using Ryujinx.Graphics.Gpu.Engine.Types;
using Ryujinx.Graphics.Gpu.Image;
using Ryujinx.Graphics.Gpu.Memory;
using Ryujinx.Graphics.Gpu.Shader.DiskCache;
using Ryujinx.Graphics.Shader;
using Ryujinx.Graphics.Shader.Translation;
using System;
using System.Collections.Generic;
using System.IO;
using System.Threading;

namespace Ryujinx.Graphics.Gpu.Shader
{
    /// <summary>
    /// Memory cache of shader code.
    /// </summary>
    class ShaderCache : IDisposable
    {
        /// <summary>
        /// Default flags used on the shader translation process.
        /// </summary>
        public const TranslationFlags DefaultFlags = TranslationFlags.DebugMode;

        private readonly struct TranslatedShader
        {
            public readonly CachedShaderStage Shader;
            public readonly ShaderProgram Program;

            public TranslatedShader(CachedShaderStage shader, ShaderProgram program)
            {
                Shader = shader;
                Program = program;
            }
        }
        ...

        /// <summary>
        /// Processes the queue of shaders that must save their binaries to the disk cache.
        /// </summary>
        public void ProcessShaderCacheQueue()
        {
            // Check to see if the binaries for previously compiled shaders are ready, and save them out.

            while (_programsToSaveQueue.TryPeek(out ProgramToSave programToSave))
            {
                ProgramLinkStatus result = programToSave.HostProgram.CheckProgramLink(false);

                if (result != ProgramLinkStatus.Incomplete)
                {
                    if (result == ProgramLinkStatus.Success)
                    {
                        _cacheWriter.AddShader(programToSave.CachedProgram, programToSave.BinaryCode ?? programToSave.HostProgram.GetBinary());
                    }

                    _programsToSaveQueue.Dequeue();
                }
                else
                {
                    break;
                }
            }
        }
    }
}
```

For other languages, our current best guidance is consistency. When editing files, keep new code and changes consistent with the style in the files. For new files, it should conform to the style for that component. If there is a completely new component, anything that is reasonably broadly accepted is fine.

Hard-fork of the Ryujinx project


# Pull Request Guide

## Contributing Rules

All contributions to Ryujinx/Ryujinx repository are made via pull requests (PRs) rather than through direct commits. The pull requests are reviewed and merged by the maintainers after a review and at least two approvals from the core development team.

To merge pull requests, you must have write permissions in the repository.

## Quick Code Review Rules

* Do not mix unrelated changes in one pull request. For example, a code style change should never be mixed with a bug fix.
* All changes should follow the existing code style. You can read more about our code style at [docs/coding-guidelines](../coding-guidelines/coding-style.md).
* Adding external dependencies is to be avoided unless not doing so would introduce _significant_ complexity. Any dependency addition should be justified and discussed before merge.
* Use Draft pull requests for changes you are still working on but want early CI loop feedback. When you think your changes are ready for review, [change the status](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/changing-the-stage-of-a-pull-request) of your pull request.
* Rebase your changes when required or directly requested. Changes should always be commited on top of the upstream branch, not the other way around.
* If you are asked to make changes during the review process do them as a new commit.
* Only resolve GitHub conversations with reviewers once they have been addressed with a commit, or via a mutual agreement.

## Pull Request Ownership

Every pull request will have automatically have labels and reviewers assigned. The label not only indicates the code segment which the change touches but also the area reviewers to be assigned.

If during the code review process a merge conflict occurs, the PR author is responsible for its resolution. Help will be provided if necessary although GitHub makes this easier by allowing simple conflict resolution using the [conflict-editor](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github).

## Pull Request Builds

When submitting a PR to the `Ryujinx/Ryujinx` repository, various builds will run validating many areas to ensure we keep developer productivity and product quality high. These various workflows can be tracked in the [Actions](https://github.com/ryujinx-mirror/Ryujinx/actions) tab of the repository. If the job continues to completion, the build artifacts will be uploaded and posted as a comment in the PR discussion.

## Review Turnaround Times

Ryujinx is a project that is maintained by volunteers on a completely free-time basis. As such we cannot guarantee any particular timeframe for pull request review and approval. Weeks to months are common for larger (>500 line) PRs but there are some additional best practises to avoid review purgatory.

* Make the reviewers life easier wherever possible. Make use of descriptive commit names, code comments and XML docs where applicable.
* If there is disagreement on feedback then always lean on the side of the development team and community over any personal opinion.
* We're human. We miss things. We forget things. If there has been radio silence on your changes for a substantial period of time then do not hesitate to reach out directly either with something simple like "bump" on GitHub or a directly on Discord.

To re-iterate, make the review as easy for us as possible, respond promptly and be comfortable to interact directly with us for anything else.

## Merging Pull Requests

Anyone with write access can merge a pull request manually when the following conditions have been met:

* The PR has been approved by two reviewers and any other objections are addressed.
    * You can request follow up reviews from the original reviewers if they requested changes.
* The PR successfully builds and passes all tests in the Continuous Integration (CI) system. In case of failures, refer to the [Actions](https://github.com/ryujinx-mirror/Ryujinx/actions) tab of your PR.

Typically, PRs are merged as one commit (squash merges). It creates a simpler history than a Merge Commit. "Special circumstances" are rare, and typically mean that there are a series of cleanly separated changes that will be too hard to understand if squashed together, or for some reason we want to preserve the ability to dissect them.

## Blocking Pull Request Merging

If for whatever reason you would like to move your pull request back to an in-progress status to avoid merging it in the current form, you can turn the PR into a draft PR by selecting the option under the reviewers section. Alternatively, you can do that by adding [WIP] prefix to the pull request title.

## Old Pull Request Policy

From time to time we will review older PRs and check them for relevance. If we find the PR is inactive or no longer applies, we will close it. As the PR owner, you can simply reopen it if you feel your closed PR needs our attention.

Hard-fork of the Ryujinx project


# Retrieval-Augmented Generation (RAG) Project

**_Think it. Build it. bRAG it._ 🚀 bRAGAI's coming soon (🤫)**

**[Join the waitlist](https://bragai.dev/)** for exclusive early access, be among the first to try your AI-powered full-stack development assistant, and transform ideas into production-ready web apps in minutes.

---------------------

This repository contains a comprehensive exploration of Retrieval-Augmented Generation (RAG) for various applications.
Each notebook provides a detailed, hands-on guide to setting up and experimenting with RAG from an introductory level to advanced implementations, including multi-querying and custom RAG builds.

![rag_detail_v2](assets/img/rag-architecture.png)

## Project Structure

If you want to jump straight into it, check out the file `full_basic_rag.ipynb` -> this file will give you a boilerplate starter code of a fully customizable RAG chatbot.

Make sure to run your files in a virtual environment (checkout section `Get Started`)

The following notebooks can be found under the directory `notebooks/`.

### [1]\_rag_setup_overview.ipynb

This introductory notebook provides an overview of RAG architecture and its foundational setup.
The notebook walks through:
- **Environment Setup**: Configuring the environment, installing necessary libraries, and API setups.
- **Initial Data Loading**: Basic document loaders and data preprocessing methods.
- **Embedding Generation**: Generating embeddings using various models, including OpenAI's embeddings.
- **Vector Store**: Setting up a vector store (ChromaDB/Pinecone) for efficient similarity search.
- **Basic RAG Pipeline**: Creating a simple retrieval and generation pipeline to serve as a baseline.

### [2]\_rag_with_multi_query.ipynb

Building on the basics, this notebook introduces multi-querying techniques in the RAG pipeline, exploring:
- **Multi-Query Setup**: Configuring multiple queries to diversify retrieval.
- **Advanced Embedding Techniques**: Utilizing multiple embedding models to refine retrieval.
- **Pipeline with Multi-Querying**: Implementing multi-query handling to improve relevance in response generation.
- **Comparison & Analysis**: Comparing results with single-query pipelines and analyzing performance improvements.

### [3]_rag_routing_and_query_construction.ipynb

This notebook delves deeper into customizing a RAG pipeline.
It covers:
- **Logical Routing:** Implements function-based routing for classifying user queries to appropriate data sources based on programming languages.
- **Semantic Routing:** Uses embeddings and cosine similarity to direct questions to either a math or physics prompt, optimizing response accuracy.
- **Query Structuring for Metadata Filters:** Defines structured search schema for YouTube tutorial metadata, enabling advanced filtering (e.g., by view count, publication date).
- **Structured Search Prompting:** Leverages LLM prompts to generate database queries for retrieving relevant content based on user input.
- **Integration with Vector Stores:** Links structured queries to vector stores for efficient data retrieval.

### [4]_rag_indexing_and_advanced_retrieval.ipynb

Continuing from the previous customization, this notebook explores:
- **Preface on Document Chunking:** Points to external resources for document chunking techniques.
- **Multi-representation Indexing:** Sets up a multi-vector indexing structure for handling documents with different embeddings and representations.
- **In-Memory Storage for Summaries:** Uses InMemoryByteStore for storing document summaries alongside parent documents, enabling efficient retrieval.
- **MultiVectorRetriever Setup:** Integrates multiple vector representations to retrieve relevant documents based on user queries.
- **RAPTOR Implementation:** Explores RAPTOR, an advanced indexing and retrieval model, linking to in-depth resources.
- **ColBERT Integration:** Demonstrates ColBERT-based token-level vector indexing and retrieval, which captures contextual meaning at a fine-grained level.
- **Wikipedia Example with ColBERT:** Retrieves information about Hayao Miyazaki using the ColBERT retrieval model for demonstration.

### [5]_rag_retrieval_and_reranking.ipynb

This final notebook brings together the RAG system components, with a focus on scalability and optimization:
- **Document Loading and Splitting:** Loads and chunks documents for indexing, preparing them for vector storage.
- **Multi-query Generation with RAG-Fusion:** Uses a prompt-based approach to generate multiple search queries from a single input question.
- **Reciprocal Rank Fusion (RRF):** Implements RRF for re-ranking multiple retrieval lists, merging results for improved relevance.
- **Retriever and RAG Chain Setup:** Constructs a retrieval chain for answering queries, using fused rankings and RAG chains to pull contextually relevant information.
- **Cohere Re-Ranking:** Demonstrates re-ranking with Cohere’s model for additional contextual compression and refinement.
- **CRAG and Self-RAG Retrieval:** Explores advanced retrieval approaches like CRAG and Self-RAG, with links to examples.
- **Exploration of Long-Context Impact:** Links to resources explaining the impact of long-context retrieval on RAG models.

## Getting Started

### Pre-requisites

Ensure **Python 3.11.11** (preferred) is installed on your system. Follow the platform-specific instructions below to install it if not already installed.

#### macOS
1. Install [Homebrew](https://brew.sh/) if not already installed:
   ```bash
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   ```
2. Install Python 3.11.11:
   ```bash
   brew install python@3.11
   ```
3. Verify installation:
   ```bash
   python3.11 --version
   ```

#### Linux
1. Update your package manager:
   ```bash
   sudo apt update
   ```
2. Install Python 3.11.11:
   ```bash
   sudo apt install python3.11 python3.11-venv
   ```
3. Verify installation:
   ```bash
   python3.11 --version
   ```

#### Windows
1. Download the Python 3.11.11 installer from [Python.org](https://www.python.org/downloads/).
2. Run the installer and ensure you check the box **"Add Python to PATH"**.
3. Verify installation:
   ```cmd
   python --version
   ```
---

### Installation Instructions

#### 1. Clone the Repository
```bash
git clone https://github.com/bRAGAI/bRAG-langchain.git
cd bRAG-langchain
```

#### 2. Create a Virtual Environment
Use Python 3.11.11 to create a virtual environment:
```bash
python3.11 -m venv venv
```

Activate the virtual environment:
- **macOS/Linux**:
  ```bash
  source venv/bin/activate
  ```
- **Windows**:
  ```cmd
  venv\Scripts\activate
  ```

#### 3. Verify and Fix Python Version
If the virtual environment defaults to a different Python version (e.g., Python 3.13):
1. Verify the current Python version inside the virtual environment:
   ```bash
   python --version
   ```
2. Use Python 3.11 explicitly within the virtual environment:
   ```bash
   python3.11
   ```
3. Ensure the `python` command uses Python 3.11 by creating a symbolic link:
   ```bash
   ln -sf $(which python3.11) $(dirname $(which python))/python
   ```
4. Verify the fix:
   ```bash
   python --version
   ```

#### 4. Install Dependencies
Install the required packages:
```bash
pip install -r requirements.txt
```

---

### Additional Steps

#### 5. Run the Notebooks
Begin with `[1]_rag_setup_overview.ipynb` to get familiar with the setup process. Proceed sequentially through the other notebooks:

- `[1]_rag_setup_overview.ipynb`
- `[2]_rag_with_multi_query.ipynb`
- `[3]_rag_routing_and_query_construction.ipynb`
- `[4]_rag_indexing_and_advanced_retrieval.ipynb`
- `[5]_rag_retrieval_and_reranking.ipynb`

#### 6. Set Up Environment Variables
1. Duplicate the `.env.example` file in the root directory and rename it to `.env`.
2. Add the following keys (replace with your actual values):

   ```env
   # LLM Model - Get key at https://platform.openai.com/api-keys
   OPENAI_API_KEY="your-api-key"

   # LangSmith - Get key at https://smith.langchain.com
   LANGCHAIN_TRACING_V2=true
   LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"
   LANGCHAIN_API_KEY="your-api-key"
   LANGCHAIN_PROJECT="your-project-name"

   # Pinecone Vector Database - Get key at https://app.pinecone.io
   PINECONE_INDEX_NAME="your-project-index"
   PINECONE_API_HOST="your-host-url"
   PINECONE_API_KEY="your-api-key"

   # Cohere - Get key at https://dashboard.cohere.com/api-keys
   COHERE_API_KEY=your-api-key
   ```

---

You're now ready to use the project!

## Usage

After setting up the environment and running the notebooks in sequence, you can:

1.  **Experiment with Retrieval-Augmented Generation**:
    Use the foundational setup in `[1]_rag_setup_overview.ipynb` to understand the basics of RAG.

2.  **Implement Multi-Querying**:
    Learn how to improve response relevance by introducing multi-querying techniques in `[2]_rag_with_multi_query.ipynb`.

## Star History

 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=bragai/brag-langchain&type=Date&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=bragai/brag-langchain&type=Date" />

 </picture>

## Contact
Do you have questions or want to collaborate? Please open an issue or email Taha Ababou at taha@bragai.dev

`If this project helps you, consider buying me a coffee ☕. Your support helps me keep contributing to the open-source community!`

    The notebooks and visual diagrams were inspired by Lance Martin's LangChain Tutorial.

README.md

Everything you need to know to build your own RAG application


### Here are all the sources used to write-up the `[1]_rag_setup_overview.ipynb` file:

1. LangSmith Documentation: https://docs.smith.langchain.com/
2. RAG Quickstart: https://python.langchain.com/docs/tutorials/rag/
3. Count Tokens: https://github.com/openai/openai-cookbook/blob/main/examples/How_to_count_tokens_with_tiktoken.ipynb
4. Text Embedding Models: https://python.langchain.com/docs/integrations/text_embedding/openai
5. Cosine Similarity: https://platform.openai.com/docs/guides/embeddings/frequently-asked-questions
6. Document Loaders: https://python.langchain.com/docs/integrations/document_loaders/
7. Splitter: https://python.langchain.com/docs/how_to/recursive_text_splitter/
8. Vectorstores: https://python.langchain.com/docs/integrations/vectorstores/
9. RAG Chains: https://python.langchain.com/docs/how_to/sequence/

These links provide additional resources and documentation related to the concepts discussed in the file.

docs/[1]_sources.md


### Here are all the sources used to write-up the `[2]_rag_with_multi_query.ipynb` file:

1. LangSmith Documentation: https://docs.smith.langchain.com/
2. Multi Query Retriever Documentation: https://python.langchain.com/docs/how_to/MultiQueryRetriever/
3. RAG Fusion Documentation: https://github.com/langchain-ai/langchain/blob/master/cookbook/rag_fusion.ipynb?ref=blog.langchain.dev
4. Forget RAG Blog: https://medium.com/towards-data-science/forget-rag-the-future-is-rag-fusion-1147298d8ad1
5. Research Papers:
   1. **Least-To-Most Prompting Enables Complex Reasoning In Large Language Models**: https://arxiv.org/pdf/2205.10625.pdf
   2. **Interleaving Retrieval with Chain-of-Thought Reasoning for Knowledge-Intensive Multi-Step Questions**: https://arxiv.org/abs/2212.10509.pdf
   3. **Take A Step Back: Evoking Reasoning Via Abstraction In Large Language Models**: https://arxiv.org/pdf/2310.06117.pdf
   4. **HyDE Paper**: https://arxiv.org/abs/2212.10496
6. HyDE Documentation: https://github.com/langchain-ai/langchain/blob/master/cookbook/hypothetical_document_embeddings.ipynb

docs/[2]_sources.md


### Here are all the sources used to write-up the `[3]_rag_routing_and_query_construction.ipynb` file:

1. https://docs.smith.langchain.com/ (LangSmith documentation)
2. https://python.langchain.com/docs/how_to/routing/ (Expression language & Embedding Router cookbook)
3. https://smith.langchain.com/public/c2ca61b4-3810-45d0-a156-3d6a73e9ee2a/r (Trace example)
4. https://smith.langchain.com/public/98c25405-2631-4de8-b12a-1891aded3359/r (Additional trace example)
5. https://blog.langchain.dev/query-construction/ (Query construction blog post)
6. https://blog.langchain.dev/enhancing-rag-based-applications-accuracy-by-constructing-and-leveraging-knowledge-graphs/ (Knowledge graphs in RAG)
7. https://python.langchain.com/v0.1/docs/use_cases/query_analysis/ (Query analysis documentation)
8. https://python.langchain.com/docs/how_to/self_query/ (Self-querying documentation)

These links provide additional resources and documentation related to the concepts discussed in the file.

docs/[3]_sources.md


### Here are all the sources used to write-up the `[4]_rag_indexing_and_advanced_retrieval.ipynb` file:

1. https://www.youtube.com/watch?v=8OJC21T2SL4 (Greg Kamradt's video on document chunking)
2. https://docs.smith.langchain.com/ (LangSmith documentation)
3. https://blog.langchain.dev/semi-structured-multi-modal-rag/ (Semi-structured multi-modal RAG)
4. https://python.langchain.com/docs/how_to/multi_vector/ (Multi-vector retrievers)
5. https://arxiv.org/abs/2312.06648 (Dense X Retrieval research paper)
6. https://python.langchain.com/docs/how_to/parent_document_retriever/ (Parent Document Retriever documentation)
7. https://www.youtube.com/watch?v=jbGchdTL7d0 (LangChain video on advanced retrieval)
8. https://arxiv.org/pdf/2401.18059 (RAPTOR research paper)
9. https://github.com/langchain-ai/langchain/blob/master/cookbook/RAPTOR.ipynb (RAPTOR implementation cookbook)

These links provide additional resources and documentation related to the concepts discussed in the file.

docs/[4]_sources.md


### Here are all the sources used to write-up the `[5]_rag_retrieval_and_reranking.ipynb` file:

1. https://docs.smith.langchain.com/ (LangSmith documentation)
2. https://python.langchain.com/docs/integrations/retrievers/cohere-reranker#doing-reranking-with-coherererank (Cohere Re-Rank)
3. https://txt.cohere.com/rerank/ (Cohere Rerank documentation)
4. https://www.youtube.com/watch?v=E2shqsYwxck (CRAG Deep Dive)
5. https://github.com/langchain-ai/langgraph/blob/main/examples/rag/langgraph_crag.ipynb (CRAG notebook)
6. https://github.com/langchain-ai/langgraph/blob/main/examples/rag/langgraph_crag.ipynb (CRAG notebook)
7. https://github.com/langchain-ai/langgraph/tree/main/examples/rag (RAG examples)
8. https://www.youtube.com/watch?v=SsHUNfhF32s (Long context impact deep dive)
9.  https://docs.google.com/presentation/d/1mJUiPBdtf58NfuSEQ7pVSEQ2Oqmek7F1i4gBwR6JDss/edit#slide=id.g26c0cb8dc66_0_0 (Slides)

These links provide additional resources and documentation related to the concepts discussed in the file.

docs/[5]_sources.md


---
name: Bug report
about: Create a report to help us improve
title: ''
labels: ''
assignees: ''

---

**Describe the bug**
A clear and concise description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

**Expected behavior**
A clear and concise description of what you expected to happen.

**Screenshots**
If applicable, add screenshots to help explain your problem.

**Desktop (please complete the following information):**
 - OS: [e.g. iOS]
 - Browser [e.g. chrome, safari]
 - Version [e.g. 22]

**Smartphone (please complete the following information):**
 - Device: [e.g. iPhone6]
 - OS: [e.g. iOS8.1]
 - Browser [e.g. stock browser, safari]
 - Version [e.g. 22]

**Additional context**
Add any other context about the problem here.


---
name: Feature request
about: Suggest an idea for this project
title: ''
labels: ''
assignees: ''

---

**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

**Describe the solution you'd like**
A clear and concise description of what you want to happen.

**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.

**Additional context**
Add any other context or screenshots about the feature request here.


## 🔥🔥🔥 News!!
* Feb 17, 2025: 👋 We release the inference code and model weights of Step-Video-T2V. [Download](https://huggingface.co/stepfun-ai/stepvideo-t2v)
* Feb 17, 2025: 👋 We release the inference code and model weights of Step-Video-T2V-Turbo. [Download](https://huggingface.co/stepfun-ai/stepvideo-t2v-turbo)
* Feb 17, 2025: 🎉 We have made our technical report available as open source. [Read](https://arxiv.org/abs/2502.10248)

## Video Demos

    <video src="https://github.com/user-attachments/assets/9274b351-595d-41fb-aba3-f58e6e91603a" width="100%" controls autoplay loop muted></video>
    <video src="https://github.com/user-attachments/assets/2f6b3ad5-e93b-436b-98bc-4701182d8652" width="100%" controls autoplay loop muted></video>
    <video src="https://github.com/user-attachments/assets/67d20ee7-ad78-4b8f-80f6-3fdb00fb52d8" width="100%" controls autoplay loop muted></video>

    <video src="https://github.com/user-attachments/assets/9abce409-105d-4a8a-ad13-104a98cc8a0b" width="100%" controls autoplay loop muted></video>
    <video src="https://github.com/user-attachments/assets/8d1e1a47-048a-49ce-85f6-9d013f2d8e89" width="100%" controls autoplay loop muted></video>
    <video src="https://github.com/user-attachments/assets/32cf4bd1-ec1f-4f77-a488-cd0284aa81bb" width="100%" controls autoplay loop muted></video>

    <video src="https://github.com/user-attachments/assets/f95a7a49-032a-44ea-a10f-553d4e5d21c6" width="100%" controls autoplay loop muted></video>
    <video src="https://github.com/user-attachments/assets/3534072e-87d9-4128-a87f-28fcb5d951e0" width="100%" controls autoplay loop muted></video>
    <video src="https://github.com/user-attachments/assets/6d893dad-556d-4527-a882-666cba3d10e9" width="100%" controls autoplay loop muted></video>

## Table of Contents

1. [Introduction](#1-introduction)
2. [Model Summary](#2-model-summary)
3. [Model Download](#3-model-download)
4. [Model Usage](#4-model-usage)
5. [Benchmark](#5-benchmark)
6. [Online Engine](#6-online-engine)
7. [Citation](#7-citation)
8. [Acknowledgement](#8-ackownledgement)

## 1. Introduction
We present **Step-Video-T2V**, a state-of-the-art (SoTA) text-to-video pre-trained model with 30 billion parameters and the capability to generate videos up to 204 frames. To enhance both training and inference efficiency, we propose a deep compression VAE for videos, achieving 16x16 spatial and 8x temporal compression ratios. Direct Preference Optimization (DPO) is applied in the final stage to further enhance the visual quality of the generated videos. Step-Video-T2V's performance is evaluated on a novel video generation benchmark, **Step-Video-T2V-Eval**, demonstrating its SoTA text-to-video quality compared to both open-source and commercial engines.

## 2. Model Summary
In Step-Video-T2V, videos are represented by a high-compression Video-VAE, achieving 16x16 spatial and 8x temporal compression ratios. User prompts are encoded using two bilingual pre-trained text encoders to handle both English and Chinese. A DiT with 3D full attention is trained using Flow Matching and is employed to denoise input noise into latent frames, with text embeddings and timesteps serving as conditioning factors. To further enhance the visual quality of the generated videos, a video-based DPO approach is applied, which effectively reduces artifacts and ensures smoother, more realistic video outputs.

### 2.1. Video-VAE
A deep compression Variational Autoencoder (VideoVAE) is designed for video generation tasks, achieving 16x16 spatial and 8x temporal compression ratios while maintaining exceptional video reconstruction quality. This compression not only accelerates training and inference but also aligns with the diffusion process's preference for condensed representations.

### 2.2. DiT w/ 3D Full Attention
Step-Video-T2V is built on the DiT architecture, which has 48 layers, each containing 48 attention heads, with each head’s dimension set to 128. AdaLN-Single is leveraged to incorporate the timestep condition, while QK-Norm in the self-attention mechanism is introduced to ensure training stability. Additionally, 3D RoPE is employed, playing a critical role in handling sequences of varying video lengths and resolutions.

### 2.3. Video-DPO
In Step-Video-T2V, we incorporate human feedback through Direct Preference Optimization (DPO) to further enhance the visual quality of the generated videos. DPO leverages human preference data to fine-tune the model, ensuring that the generated content aligns more closely with human expectations. The overall DPO pipeline is shown below, highlighting its critical role in improving both the consistency and quality of the video generation process.

## 3. Model Download
| Models   | 🤗Huggingface    |  🤖Modelscope |
|:-------:|:-------:|:-------:|
| Step-Video-T2V | [download](https://huggingface.co/stepfun-ai/stepvideo-t2v) | [download](https://www.modelscope.cn/models/stepfun-ai/stepvideo-t2v)
| Step-Video-T2V-Turbo (Inference Step Distillation) | [download](https://huggingface.co/stepfun-ai/stepvideo-t2v-turbo) | [download](https://www.modelscope.cn/models/stepfun-ai/stepvideo-t2v-turbo)

## 4. Model Usage
### 📜 4.1  Requirements

The following table shows the requirements for running Step-Video-T2V model (batch size = 1, w/o cfg distillation) to generate videos:

|     Model    |  height/width/frame |  Peak GPU Memory | 50 steps w flash-attn | 50 steps w/o flash-attn |
|:------------:|:------------:|:------------:|:------------:|:------------:|
| Step-Video-T2V   |        768px768px204f      |  78.55 GB | 860 s | 1437 s |
| Step-Video-T2V   |        544px992px204f      |  77.64 GB | 743 s | 1232 s |
| Step-Video-T2V   |        544px992px136f      |  72.48 GB | 408 s | 605 s |

* An NVIDIA GPU with CUDA support is required.
  * The model is tested on four GPUs.
  * **Recommended**: We recommend to use GPUs with 80GB of memory for better generation quality.
* Tested operating system: Linux
* The self-attention in text-encoder (step_llm) only supports CUDA capabilities sm_80 sm_86 and sm_90

### 🔧 4.2 Dependencies and Installation
- Python >= 3.10.0 (Recommend to use [Anaconda](https://www.anaconda.com/download/#linux) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html))
- [PyTorch >= 2.3-cu121](https://pytorch.org/)
- [CUDA Toolkit](https://developer.nvidia.com/cuda-downloads)
- [FFmpeg](https://www.ffmpeg.org/)
```bash
git clone https://github.com/stepfun-ai/Step-Video-T2V.git
conda create -n stepvideo python=3.10
conda activate stepvideo

cd Step-Video-T2V
pip install -e .
pip install flash-attn --no-build-isolation  ## flash-attn is optional
```

###  🚀 4.3 Inference Scripts

#### Multi-GPU Parallel Deployment

- We employed a decoupling strategy for the text encoder, VAE decoding, and DiT to optimize GPU resource utilization by DiT. As a result, a dedicated GPU is needed to handle the API services for the text encoder's embeddings and VAE decoding.
```bash
python api/call_remote_server.py --model_dir where_you_download_dir &  ## We assume you have more than 4 GPUs available. This command will return the URL for both the caption API and the VAE API. Please use the returned URL in the following command.

parallel=4  # or parallel=8
url='127.0.0.1'
model_dir=where_you_download_dir

torchrun --nproc_per_node $parallel run_parallel.py --model_dir $model_dir --vae_url $url --caption_url $url  --ulysses_degree $parallel --prompt "一名宇航员在月球上发现一块石碑，上面印有“stepfun”字样，闪闪发光" --infer_steps 50  --cfg_scale 9.0 --time_shift 13.0
```

#### Single-GPU Inference and Quantization

- The open-source project DiffSynth-Studio by ModelScope offers single-GPU inference and quantization support, which can significantly reduce the VRAM required. Please refer to [their examples](https://github.com/modelscope/DiffSynth-Studio/tree/main/examples/stepvideo) for more information.

###  🚀 4.4 Best-of-Practice Inference settings
Step-Video-T2V exhibits robust performance in inference settings, consistently generating high-fidelity and dynamic videos. However, our experiments reveal that variations in inference hyperparameters can have a substantial effect on the trade-off between video fidelity and dynamics. To achieve optimal results, we recommend the following best practices for tuning inference parameters:

| Models   | infer_steps   | cfg_scale  | time_shift | num_frames |
|:-------:|:-------:|:-------:|:-------:|:-------:|
| Step-Video-T2V | 30-50 | 9.0 |  13.0 | 204
| Step-Video-T2V-Turbo (Inference Step Distillation) | 10-15 | 5.0 | 17.0 | 204 |

## 5. Benchmark
We are releasing [Step-Video-T2V Eval](https://github.com/stepfun-ai/Step-Video-T2V/blob/main/benchmark/Step-Video-T2V-Eval) as a new benchmark, featuring 128 Chinese prompts sourced from real users. This benchmark is designed to evaluate the quality of generated videos across 11 distinct categories: Sports, Food, Scenery, Animals, Festivals, Combination Concepts, Surreal, People, 3D Animation, Cinematography, and Style.

## 6. Online Engine
The online version of Step-Video-T2V is available on [跃问视频](https://yuewen.cn/videos), where you can also explore some impressive examples.

## 7. Citation
```
@misc{ma2025stepvideot2vtechnicalreportpractice,
      title={Step-Video-T2V Technical Report: The Practice, Challenges, and Future of Video Foundation Model},
      author={Guoqing Ma and Haoyang Huang and Kun Yan and Liangyu Chen and Nan Duan and Shengming Yin and Changyi Wan and Ranchen Ming and Xiaoniu Song and Xing Chen and Yu Zhou and Deshan Sun and Deyu Zhou and Jian Zhou and Kaijun Tan and Kang An and Mei Chen and Wei Ji and Qiling Wu and Wen Sun and Xin Han and Yanan Wei and Zheng Ge and Aojie Li and Bin Wang and Bizhu Huang and Bo Wang and Brian Li and Changxing Miao and Chen Xu and Chenfei Wu and Chenguang Yu and Dapeng Shi and Dingyuan Hu and Enle Liu and Gang Yu and Ge Yang and Guanzhe Huang and Gulin Yan and Haiyang Feng and Hao Nie and Haonan Jia and Hanpeng Hu and Hanqi Chen and Haolong Yan and Heng Wang and Hongcheng Guo and Huilin Xiong and Huixin Xiong and Jiahao Gong and Jianchang Wu and Jiaoren Wu and Jie Wu and Jie Yang and Jiashuai Liu and Jiashuo Li and Jingyang Zhang and Junjing Guo and Junzhe Lin and Kaixiang Li and Lei Liu and Lei Xia and Liang Zhao and Liguo Tan and Liwen Huang and Liying Shi and Ming Li and Mingliang Li and Muhua Cheng and Na Wang and Qiaohui Chen and Qinglin He and Qiuyan Liang and Quan Sun and Ran Sun and Rui Wang and Shaoliang Pang and Shiliang Yang and Sitong Liu and Siqi Liu and Shuli Gao and Tiancheng Cao and Tianyu Wang and Weipeng Ming and Wenqing He and Xu Zhao and Xuelin Zhang and Xianfang Zeng and Xiaojia Liu and Xuan Yang and Yaqi Dai and Yanbo Yu and Yang Li and Yineng Deng and Yingming Wang and Yilei Wang and Yuanwei Lu and Yu Chen and Yu Luo and Yuchu Luo and Yuhe Yin and Yuheng Feng and Yuxiang Yang and Zecheng Tang and Zekai Zhang and Zidong Yang and Binxing Jiao and Jiansheng Chen and Jing Li and Shuchang Zhou and Xiangyu Zhang and Xinhao Zhang and Yibo Zhu and Heung-Yeung Shum and Daxin Jiang},
      year={2025},
      eprint={2502.10248},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2502.10248},
}
```

## 8. Acknowledgement
- We would like to express our sincere thanks to the [xDiT](https://github.com/xdit-project/xDiT) team for their invaluable support and parallelization strategy.
- Our code will be integrated into the official repository of [Huggingface/Diffusers](https://github.com/huggingface/diffusers).
- We thank the [FastVideo](https://github.com/hao-ai-lab/FastVideo) team for their continued collaboration and look forward to launching inference acceleration solutions together in the near future.

README.md