piker
-----
trading gear for hackers

|gh_actions|

.. |gh_actions| image:: https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fpikers%2Fpiker%2Fbadge&style=popout-square
    :target: https://actions-badge.atrox.dev/piker/pikers/goto

``piker`` is a broker agnostic, next-gen FOSS toolset and runtime for
real-time computational trading targeted at `hardcore Linux users
<comp_trader>`_ .

we use much bleeding edge tech including (but not limited to):

- latest python for glue_
- uv_ for packaging and distribution
- trio_ & tractor_ for our distributed `structured concurrency`_ runtime
- Qt_ for pristine low latency UIs
- pyqtgraph_ (which we've extended) for real-time charting and graphics
- ``polars`` ``numpy`` and ``numba`` for redic `fast numerics`_
- `apache arrow and parquet`_ for time-series storage

potential projects we might integrate with soon,

- (already prototyped in ) techtonicdb_ for L2 book storage

.. _comp_trader: https://jfaleiro.wordpress.com/2019/10/09/computational-trader/
.. _glue: https://numpy.org/doc/stable/user/c-info.python-as-glue.html#using-python-as-glue
.. _uv: https://docs.astral.sh/uv/
.. _trio: https://github.com/python-trio/trio
.. _tractor: https://github.com/goodboy/tractor
.. _structured concurrency: https://trio.discourse.group/
.. _Qt: https://www.qt.io/
.. _pyqtgraph: https://github.com/pyqtgraph/pyqtgraph
.. _apache arrow and parquet: https://arrow.apache.org/faq/
.. _fast numerics: https://zerowithdot.com/python-numpy-and-pandas-performance/
.. _techtonicdb: https://github.com/0b01/tectonicdb


focus and feats:
****************
fitting with these tenets, we're always open to new
framework/lib/service interop suggestions and ideas!

- **100% federated**:
  your code, your hardware, your data feeds, your broker fills.

- **zero web**:
  low latency as a prime objective, native UIs and modern IPC
  protocols without trying to re-invent the "OS-as-an-app"..

- **maximal privacy**:
  prevent brokers and mms from knowing your planz; smack their
  spreads with dark volume from a VPN tunnel.

- **zero clutter**:
  modal, context oriented UIs that echew minimalism, reduce thought
  noise and encourage un-emotion.

- **first class parallelism**:
  built from the ground up on a next-gen structured concurrency
  supervision sys.

- **traders first**:
  broker/exchange/venue/asset-class/money-sys agnostic

- **systems grounded**:
  real-time financial signal processing (fsp) that will make any
  queuing or DSP eng juice their shorts.

- **non-tina UX**:
  sleek, powerful keyboard driven interaction with expected use in
  tiling wms (or maybe even a DDE).

- **data collab at scale**:
  every actor-process and protocol is multi-host aware.

- **fight club ready**:
  zero interest in adoption by suits; no corporate friendly license,
  ever.

building the hottest looking, fastest, most reliable, keyboard
friendly FOSS trading platform is the dream; join the cause.


a sane install with `uv`
************************
bc why install with `python` when you can faster with `rust` ::

    uv sync

    # ^ astral's docs,
    # https://docs.astral.sh/uv/concepts/projects/sync/

include all GUIs (ex. for charting)::

    uv sync --group uis

AND with **all** our normal hacking tools::

    uv sync --dev

AND if you want to try WIP integrations::

    uv sync --all-groups

Ensure you can run the root-daemon::

    uv run pikerd [-l info --pdb]


install on nix(os)
******************
``NixOS`` is our core devs' distro of choice for which we offer
a stringently defined development shell envoirment that can currently
be applied in one of 2 ways::

    # ONLY if running on X11
    nix-shell default.nix

Or if you prefer flakes style and a modern DE::

    # ONLY if also running on Wayland
    nix develop  # for default bash
    nix develop -c uv run xonsh  # for @goodboy's preferred sh B)


start a chart
*************
run a realtime OHLCV chart stand-alone::

    [uv run] piker -l info chart btcusdt.spot.binance xmrusdt.spot.kraken

    # ^^^ iff you haven't activated the py-env,
    # - https://docs.astral.sh/uv/concepts/projects/run/
    #
    # in order to create an explicit virt-env see,
    # - https://docs.astral.sh/uv/concepts/projects/layout/#the-project-environment
    # - https://docs.astral.sh/uv/pip/environments/
    #
    # use $UV_PROJECT_ENVIRONMENT to select any non-`.venv/`
    # as the venv sudir in the repo's root.
    # - https://docs.astral.sh/uv/reference/environment/#uv_project_environment

this runs a chart UI (with 1m sampled OHLCV) and shows 2 spot markets from 2 diff cexes
overlayed on the same graph. Use of `piker` without first starting
a daemon (`pikerd` - see below) means there is an implicit spawning of the
multi-actor-runtime (implemented as a `tractor` app).

For additional subsystem feats available through our chart UI see the
various sub-readmes:

- order control using a mouse-n-keyboard UX B)
- cross venue market-pair (what most call "symbol") search, select, overlay Bo
- financial-signal-processing (`piker.fsp`) write-n-reload to sub-chart BO
- src-asset derivatives scan for anal, like the infamous "max pain" XO


spawn a daemon standalone
*************************
we call the root actor-process the ``pikerd``. it can be (and is
recommended normally to be) started separately from the ``piker
chart`` program::

    pikerd -l info --pdb

the daemon does nothing until a ``piker``-client (like ``piker
chart``) connects and requests some particular sub-system. for
a connecting chart ``pikerd`` will spawn and manage at least,

- a data-feed daemon: ``datad`` which does all the work of comms with
  the backend provider (in this case the ``binance`` cex).
- a paper-trading engine instance, ``paperboi.binance``, (if no live
  account has been configured) which allows for auto/manual order
  control against the live quote stream.

*using* an actor-service (aka micro-daemon) manager which dynamically
supervises various sub-subsystems-as-services throughout the ``piker``
runtime-stack.

now you can (implicitly) connect your chart::

    piker chart btcusdt.spot.binance

since ``pikerd`` was started separately you can now enjoy a persistent
real-time data stream tied to the daemon-tree's lifetime. i.e. the next
time you spawn a chart it will obviously not only load much faster
(since the underlying ``datad.binance`` is left running with its
in-memory IPC data structures) but also the data-feed and any order
mgmt states should be persistent until you finally cancel ``pikerd``.


if anyone asks you what this project is about
*********************************************
you don't talk about it; just use it.


how do i get involved?
**********************
enter the matrix.


how come there ain't that many docs
***********************************
i mean we want/need them but building the core right has been higher
prio then marketting (and likely will stay that way Bp).

soo, suck it up bc,

- no one is trying to sell you on anything
- learning the code base is prolly way more valuable
- the UI/UXs are intended to be "intuitive" for any hacker..

we obviously need tonz help so if you want to start somewhere and
can't necessarily write "advanced" concurrent python/rust code, this
helping document literally anything might be the place for you!
