Metadata-Version: 2.1
Name: agentos
Version: 0.0.7
Summary: AgentOS is a command line interface and python developer API for building, running, and sharing flexible learning agents.
Home-page: https://agentos.org
Author: Andy Konwinski
License: Apache License 2.0
Project-URL: Source Code, https://github.com/agentos-project/agentos
Keywords: reinforcement learning ai agent
Platform: UNKNOWN
Requires-Python: >=3.5
Requires-Dist: click (>=7.0)
Requires-Dist: mlflow (==1.9.1)
Requires-Dist: gym (==0.17.1)
Requires-Dist: numpy (==1.18.5)

==================================
AgentOS: a learning agent platform
==================================

AgentOS is an open source **Python API and a command line interface** for
building, running, and sharing learning agents. AgentOS is licensed under the
Apache License, Version 2.0.

Key features include:
  * Easy to use Agent API for developing and running new agents.

  * Example learning agents from different disciplines and research areas are
    available in the
    `example_agents
    <https://github.com/agentos-project/agentos/tree/master/example_agents>`_
    directory of the project source code.

  * Reuse of OpenAI's Gym Environment abstraction.

.. image:: https://github.com/agentos-project/agentos/workflows/Tests%20on%20master/badge.svg
  :target: https://github.com/agentos-project/agentos/actions
  :alt: Test Status Indicator

AgentOS is beta software, APIs and overall architecture are likely to change
significantly over time.


The AgentOS docs are at `agentos.org <https://agentos.org>`_.


Install and Explore
===================

AgentOS requires Python 3.5 - 3.8 and `conda`. To get started, use pip to
install agentos, and then run a simple agent::

  # Make sure you're using Python 3.5 - 3.8
  # Make sure you have miniforge, miniconda, or conda installed (required
  # for `agentos run`, which uses MLflow Projects).
  pip install agentos
  agentos run agentos.agents.RandomAgent gym.envs.classic_control.CartPoleEnv

Then, create and run your first Agent::

  mkdir my_agent
  cd my_agent
  agentos init
  agentos run

This type of agent is called an **Agent Directory**. To see more complex
agents, look at example agents in the `example_agents
<https://github.com/agentos-project/agentos/tree/master/example_agents>`_
directory of the project source code.


Development Process
===================

AgentOS uses `GitHub Issues
<https://github.com/agentos-project/agentos/issues>`_ to 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 the `Proposing Features`_ section.

To contribute to AgentOS, the general workflow is as follows:

* Sync with the core development team via the
  `issue tracker <https://github.com/agentos-project/agentos/issues>`_
  so 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 Features
==================

For new features and other big chunks of work, AgentOS maintains a `repo of
design documents <https://github.com/agentos-project/design_docs>`_.  The goal
of these design documents is to:

* Allow developers to think through a design, and
* Allow stakeholders to give feedback

before development begins.

If you'd like to propose a feature, please follow the procedure found in the
`design_docs README
<https://github.com/agentos-project/design_docs/blob/main/README.rst>`_.  You
can also browse other design docs in the repo to get a feel for the general
content and style.


Installing AgentOS From Source
==============================

To 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.


Testing
=======
To run tests::

  cd agentos # the project root, not the nested agentos/agentos dir
  pip install -r dev-requirements.txt
  pytest test_all.py

Also, we use Github Actions to run ``test_all.py`` with every commit and pull
request (see the `test workflow
<https://github.com/agentos-project/agentos/blob/master/.github/workflows/run-tests.yml>`_)


Building Docs
=============

The documentation source is in the ``documentation`` directory and written in
`ReStructuredText <https://docutils.sourceforge.io/rst.html>`_.  The docs are
built using `Sphinx <https://www.sphinx-doc.org>`_.  To build the docs, first
install the dev requirements::

  pip install -r dev-requirements.txt

Then use the build script::

  python scripts/build_docs.py

Use the ``--help`` flag to learn more about other optional flags that
``build_docs.py`` takes, 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 into ``docs/<version_num>``
where ``version_num`` comes from ``agentos/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.org
==============================

`agentos.org <https://agentos.org>`_ is a github.io website where the AgentOS
docs are hosted.  To publish updated docs to agentos.org, checkout the
``website`` branch and build the docs per the instructions above, then create a
PR against the ``agentos-dev/website`` branch. Once committed, those changes
will become live at agentos.org automatically.

Assuming you have local branches tracking both the ``master`` and ``website``
branches, and all changes to the documentation source files have all been
committed in the ``master`` branch, 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 push


Building README.rst
===================

The main project ``README.rst`` is built via the script
``python 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 update ``README.rst``, first familiarize yourself with its build script
``scripts/build_readme.py``. There you can see which sections of
documentation are included in ``README.rst``, plus some text that is manually
inserted directly into ``README.rst`` (e.g., the footer).


Releasing
=========

Here are the steps for releasing AgentOS:

#. Create a release pull request (PR) that:

   * Removes "-alpha" suffix from the version number in ``agentos/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 against ``website`` branch. This is required for all releases,
   even if the docs have not changed, since the docs are versioned. When you
   run the ``build_docs.py`` script, you will use the ``--release`` flag
   (see `Building Docs`_ & `Publishing Docs to agentos.org`_ for more details).

#. Create another follow-on PR that bumps version number to be ``X.Y.Z-alpha``
   which reflects that work going forward will be part of the next release
   (we use `semantic versioning <https://semver.org>`_).

#. Push the release to PyPI (see `Pushing Releases to PyPI`_).

#. Create a `github release
   <https://github.com/agentos-project/agentos/releases>`_ that includes zips
   and tarzips of `wheel files <https://wheel.readthedocs.io/en/stable/>`_
   and source code (which you can generate using ``python setup.py sdist
   --formats=gztar,zip bdist_wheel`` and then manually upload to the release).


Pushing Releases to PyPI
========================

We make AgentOS `available in PyPI <https://pypi.org/project/agentos/>`_. To
push a release to PyPI, you can approximately follow `these python.org
instructions <https://packaging.python.org/tutorials/packaging-projects/>`_,
which will probably look something like::

  pip install setuptools wheel twine
  python setup.py sdist --formats=gztar,zip bdist_wheel
  twine upload dist/*


----

*This README was compiled from the project documentation via:*
``python documentation/build_readme.py``.

