Package: agentos
This project consists of two major pieces: the Python Component System (PCS)
and AgentOS.Python Component System (PCS)PCS is an open sourcePython API, command line interface, and public web
registryfor building, running, and sharing Python programs.  The goals of
PCS are to:Make Python program execution reproducible.Transparently manage Python virtual environments while providing a Python API
forpipandvirtualenv.Simplify experiment tracking and code sharing.PCS does this by allowing you to explicitly specify dependencies and arguments
for your program and then providing a thin runtime (currently based onMLflow) to automatically instrument your program’s execution.
PCS is compatible with most frameworks that are used to build machine learning
and reinforcement learning systems.AgentOSAgentOS is a set of libraries built on top of the Python Component System that
make it easy to build, run, and share agents that use Reinforcement Learning
(RL) to solve tasks.Key features of AgentOS:Easy to use Agent API for developing and running new agents.Apublic repositoryof popular RL
environments and agents, and runs of those agents in those environments
that can be reproduced with a single line of code.Example learning agents from different disciplines and research areas are
available in theexample_agentsdirectory of the project source code.ConnectAsk questions or report bugs in PCS and AgentOS inGitHub Issuesor on thedev Discord.Find theAgentOS source code on Github.The Python Component System and AgentOS are alpha software; APIs and overall
architecture are likely to change significantly over time.  They are
licensed under the Apache License, Version 2.0.QuickstartSee the agentos.orgquickstarts.DocumentationFor detailed documentation see theagentos.org docs.Development ProcessAgentOS usesGitHub Issuesto track development
work.  Submit any bug reports or feature requests to this issues tracker.For significant feature work (more than a couple dev days or something that
fundamentally changes internal or external interfaces), we run a design process
to solicit feedback from other collaborators.  Read more about this process
in theProposing Featuressection.To contribute to AgentOS, the general workflow is as follows:Sync with the core development team via theissue trackerso we can avoid unnecessary or duplicated work.Fork the AgentOS repo.Complete your feature work on a branch in your forked repo.  Ensure all
checks and tests pass.Issue a pull request from your forked repo into the central AgentOS repo.
Assign a core developer to review.Address any comments and the core developer will merge once the PR looks
good.Proposing FeaturesFor new features and other big chunks of work, AgentOS uses a design process
centered around design proposals, discussions, and design docs. The goal of the
process is to:Allow developers to think through a design, andAllow stakeholders to give feedback…before development begins.If you’d like to propose a feature, please follow the procedure found in thedesign_docs README.  You can also
browse existing design docs in the folder to get a feel for the general
content and style.Installing AgentOS From SourceTo install agentos from source (e.g., to play with the example_agents), run the
following:git clone https://github.com/agentos-project/agentos.git
pip install -e agentos # you may want to do this in a virtualenv or conda env.TestingTo run tests, first install the requirements (note, this script installs the
Python requirements into the currently active virtual environment):cd agentos # the project root, not the nested agentos/agentos dir
python install_requirements.pyThen run the tests:pytestAlso, we use Github Actions to run tests with every commit
and pull request (see thetest workflow)If you want to the CLI to interact with a local development server, define the
environment variable (or create a.envfile)USE_LOCAL_SERVER=True.To run website tests:python install_requirements.py
cd web # the web directory contained in project root
python manage.py testNote that some tests (e.g., seeweb/registry/tests/test_integration.py)
test functionality for interacting with github repositories by fetching code
fromhttps://github.com/agentos-project/agentos. Where possible, in order to
make it easy to have those tests run against code in a github repo that you can
change during development without disrupting other PRs, the test code uses
global variables defined intests/utils.pyto decide which github
repo to use when testing.If you make changes to code that is fetched from github for use by tests, then
please follow this process for your PR:While doing development, change theTESTING_GITHUB_REPO_URLand/orTESTING_BRANCH_NAMEglobal variables intests/utils.pyto point to a version of your PR branch that you’ve pushed to
github. We recommend commenting out the default “prod” values of these
variables so that you can uncomment them in the next step when the PR
is approved for merge.After your PR is approved and right before it is merged, push the branch
you used during testing to thetest_prodbranch of the agentos-project
accounthttps://github.com/agentos-project/agentos.git. And then update
the variables intests/utils.py(you should be able to just uncomment
the lines you commented out in step 1 above, and delete the lines you added).Building DocsThe documentation source is in thedocumentationdirectory and written inReStructuredText.  The docs are
built usingSphinx.  To build the docs, first
install the dev requirements (note, this script will install requirements into
the currently active Python virtual environment):python install_requirements.pyThen use the build script:python scripts/build_docs.pyUse the--helpflag to learn more about other optional flags thatbuild_docs.pytakes, including--release(for publishing the docs) and--watch(for auto-recompiling the docs whenever doc source files are
changed).Notice that the build file puts the compiled docs intodocs/<version_num>whereversion_numcomes frompcs/version.py.Or you can build the docs manually (e.g., to control where output goes):sphinx-build documentation outdir  # Or use sphinx-autobuild.
# Open and inspect outdir/index.html in your browser.Publishing Docs to agentos.orgagentos.orgis a github.io website where the AgentOS
docs are hosted.  To publish updated docs to agentos.org, checkout thewebsitebranch and build the docs per the instructions above, then create a
PR against theagentos-dev/websitebranch. Once committed, those changes
will become live at agentos.org automatically.Assuming you have local branches tracking both themasterandwebsitebranches, and all changes to the documentation source files have all been
committed in themasterbranch, the workflow to publish updated docs to
agentos.org might look similar to:git checkout website
git merge master
python scripts/build_docs.py --release -a  # The -a is a `sphinx-build` flag.
git add docs
git commit -m "push updated docs to website for version X.Y.Z"
git pushBuilding README.rstThe main projectREADME.rstis built via the scriptpython scripts/build_readme.py, which re-uses sections of
documentation. This avoids duplication of efforts and lowers the chances
that a developer will forget to update one or the either of the README or
the docs.To updateREADME.rst, first familiarize yourself with its build scriptscripts/build_readme.py. There you can see which sections of
documentation are included inREADME.rst, plus some text that is manually
inserted directly intoREADME.rst(e.g., the footer).ReleasingHere are the steps for releasing AgentOS:Build and check the distribution artifacts for the release by running:python install_requirements.py
python setup.py sdist --formats=gztar,zip bdist_wheel
twine check dist/*This will create awheel fileas well as tar.gz and zip source distribution files, and catch any blockers
that PyPI would raise at upload time. Fix any errors before proceeding.Create a release pull request (PR) that:Removes “-alpha” suffix from the version number inpcs/version.py.Contains draft release notes (summary of major changes).Wait till the PR gets LGTMs from all other committers, then merge it.Build and publish the docs for the new version, which involves creating a
pull request againstwebsitebranch. This is required for all releases,
even if the docs have not changed, since the docs are versioned. When you
run thebuild_docs.pyscript, you will use the--releaseflag
(seeBuilding Docs&Publishing Docs to agentos.orgfor more details).Create another follow-on PR that bumps version number to beX.Y.Z-alphawhich reflects that work going forward will be part of the next release
(we usesemantic versioning).Push the release to PyPI (seePushing Releases to PyPI).Create agithub releaseand upload the
tar.gz and zip source code distribution files. This will create a git tag.
For the tag name, use “vX.Y.Z” (e.g. v0.1.0).Pushing Releases to PyPIWe make AgentOSavailable in PyPI. To
push a release to PyPI, you can approximately followthese python.org
instructions,
which will probably look something like:python install_requirements.py
rm -rf dist
python setup.py sdist --formats=gztar bdist_wheel
twine check dist/*
twine upload dist/*This README was compiled from the project documentation via:python scripts/build_readme.py.