AGENTS.md · jesse-ai/jesse

Sections

1. Overview
2. Skills
3. Key Characteristics
4. Development Workflow
5. Publishing the Docker Image
6. Important Notes
7. File Structure
8. Testing Strategy
9. Related Repositories

First lines (shown under the repo's MIT license)

# Jesse Repository Guide for AI Agents

## Overview
The jesse repository is the **core open-source framework** of the Jesse trading system. It contains the main Python codebase for backtesting trading strategies, importing historical data from crypto exchanges, running optimizations, and providing the API backend for the dashboard. It glues together the other repositories and makes them work together.

## Skills

This repo stores shared **Agent Skills** in `.claude/skills/` — focused, task-specific playbooks used by Claude Code and Codex. Codex also discovers them through the repository-relative `.agents/skills` symlink.

Before starting a task, scan the YAML frontmatter of every `.claude/skills/*/SKILL.md`. When a skill's `description` matches the task, read that `SKILL.md` completely before acting. A matching skill is the authoritative reference for what it covers, and its details are deliberately kept out of this file. This scan is the cross-platform fallback if native skill discovery or symlink support is unavailable.

- **`jesse-strategy-tests`** — conventions for writing Jesse strategy and engine tests.

## Key Characteristics

### Central Framework
- **jesse-live depends on this** - Changes here affect live trading
- **jesse-rust integrates here** - Rust functions are called from this codebase
- **dashboard consumes this API** - Frontend uses the FastAPI routes and controller files. 

### Technology Stack
- **Python** - Primary language
- **FastAPI** - API framework for all routes
- **NumPy** - Array operations and calculations
- **keewee** - ORM for the database

## Development Workflow

### Making Changes
When implementing features or fixing bugs:

1. **Understand the scope** - Determine if other repositories such as the dashboard need updates
2. **Implement the code** in the appropriate module
3. **Write/update tests** - Maintain test coverage
4. **Run tests** to verify changes:
   ```bash
   python -m pytest
   ```
5. **Consider jesse-live** - Does this affect live trading?
6. **Update API routes** if needed - Follow FastAPI patterns
7. Follow the user's local workspace instructions for restarting a development server.

### Python Environment
Use the project's active virtual environment or Conda environment. Run the commands
below from the repository root unless another working directory is specified.
`python`, `jesse`, and `pyrefly` should resolve to that environment's tools.

Verify that the interpreter meets the repository's Python version requirements.
If a compatible interpreter or the intended environment cannot be found, ask the
user which interpreter or environment to use before proceeding. Do not install
Python, create an environment, or install packages to work around a missing or
incompatible environment without explicit user authorization. Likewise, if a
required dependency or tool is missing, ask the user before installing it.

### Running Jesse Backend
Run Jesse from a Jesse project directory containing its configuration and strategies,
rather than from this framework's source directory:
```bash
jesse run
```

Use the project's configured port and log location. Restart only when authorized by
the user or local workspace instructions. Identify the process by its port and
working directory and stop only that instance gracefully; never use a broad
`pkill`. Check for active live/paper sessions and defer a disruptive restart while
they are running. Preserve unrelated processes and services. After restarting,
verify an authenticated API read succeeds on the project's configured port.

### Running Tests
Run the test suite after changes if asked.
```bash
python -m pytest
```

For a local parallel run, when `pytest-xdist` is already installed and the host has
enough CPU and memory capacity:
```bash
python -m pytest -n 12 --dist=loadfile
```
Keep file grouping so module fixtures and tests within a file run together in one
worker. Reduce the worker count on smaller hosts. Parallel execution is optional;
plain `python -m pytest` remains the serial fallback for debugging and environments
without the plugin. With the current pytest 6 requirement, use `pytest-xdist==3.5.0`;
newer plugin releases require pytest 7. Ask before installing missing test tools.

Dashboard Playwright tests start Jesse from a disposable project through
`dashboard-v1/tests/e2e/backend.mjs`. That process selects a dedicated env file
with `JESSE_ENV_FILE`, enables `IS_TEST_ENV=TRUE`, and uses a non-public
`POSTGRES_SCHEMA` containing `e2e`, `test`, or `testing`. Test-only reset/seed
routes are registered only in that mode and still require normal dashboard
authentication. Never enable `RESET_TEST_DATABASE` against `public` or a normal
development schema; the runtime guard intentionally rejects it.

If you've updated jesse-rust, build it from its own checkout using the same Python
environment, then run Jesse's tests. For sibling checkouts:
```bash
cd ../jesse-rust
./build-local.sh

cd ../jesse
python -m pytest
```

## Publishing the Docker Image

When the user asks to **"push a docker build for Jesse"** (or to "release"/"publish"
Jesse), publish by pushing a version git tag. The build runs on GitHub Actions
(`.github/workflows/docker-publish.yml`) and, on a `v*` tag push, publishes to **PyPI** and
**Docker Hub in parallel**: it uploads the package to PyPI and (independently) builds the
multi-arch `linux/amd64` + `linux/arm64` Docker image, publishing `salehmir/jesse:<version>`
and `salehmir/jesse:latest`. The two are independent — if one fails the other still
publishes; just cut a new version to retry the failed half.

Steps (run from inside `jesse/`):

1. Read the current version from `setup.py` (the `VERSION = "x.y.z"` line). Do **not**
   hardcode it — always read it fresh.
2. Tell the user which version you're about to tag and push (e.g. "Pushing docker build
   for v2.2.0").
3. Confirm the tag doesn't already exist (`git tag -l v<version>` and
   `git ls-remote --tags origin v<version>`). If it already exists, stop and ask the user
   whether to bump the version in `setup.py` (and `version.py`) first.
4. Create and push the tag:
   ```bash
   git tag v<version>
   git push origin v<version>
   ```
5. The `push: tags: ['v*']` trigger starts the workflow automatically. Optionally watch it:
   ```bash
   gh run watch --repo jesse-ai/jesse
   ```
6. When done, verify both architectures are present:
   ```bash
   docker buildx imagetools inspect salehmir/jesse:latest
   ```

Notes:
- Pushing a `v*` tag publishes **both PyPI and Docker** via this one workflow — PyPI first,
  Docker second. Do **not** also publish to PyPI manually (e.g. `twine upload`), or the tag
  push will fail on a duplicate-version upload.
- Required `jesse-ai/jesse` GitHub repo secrets: `PYPI_API_TOKEN` (PyPI),
  `DOCKERHUB_USERNAME` + `DOCKERHUB_TOKEN` (Docker Hub), and optionally
  `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID` (build notification). Nothing to configure locally.
- A manual run (`gh workflow run docker-publish.yml --repo jesse-ai/jesse`) **skips PyPI**
  and only rebuilds/pushes `salehmir/jesse:latest` — useful as a credentials smoke test.

## Important Notes

### Debugging
- **Use `jh.debug()` for all debugging output** - Never use plain `print()`
- **Log format**: `[2024-12-06 18:23:12] ==> Your message here`
- Logs include timestamps and `==>` prefix
- Essential for debugging backtests and live trading sessions

### API Routes
- **Default to POST endpoints** unless specifically asked for GET
- Use FastAPI decorators and patterns
- Follow the structure of existing routes in `jesse/routes/`
- Return proper HTTP status codes and JSON responses
- Handle errors gracefully