Metadata-Version: 2.5
Name: anomx
Version: 0.2.87
Summary: Installable time-series anomaly library with forecasting, reconstruction, and representation base approaches.
Project-URL: Homepage, https://www.anomx.io
Project-URL: Repository, https://github.com/theorieken/anomx
Project-URL: Issues, https://github.com/theorieken/anomx/issues
Author: Theo Rieken
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: anomaly-detection,data-intelligence,forecasting,machine-learning,observability,time-series
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: joblib>=1.2
Requires-Dist: narwhals>=1.25.1
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.11
Requires-Dist: tqdm>=4.64
Provides-Extra: calendar
Requires-Dist: holidays>=0.11; extra == 'calendar'
Provides-Extra: darts
Requires-Dist: darts<0.42,>=0.41; extra == 'darts'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pandas-stubs>=2.2; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Provides-Extra: interop
Requires-Dist: polars>=1.0; extra == 'interop'
Requires-Dist: xarray>=2023.1; extra == 'interop'
Provides-Extra: ml
Requires-Dist: darts[torch]<0.42,>=0.41; extra == 'ml'
Requires-Dist: onnx>=1.16; extra == 'ml'
Requires-Dist: onnxruntime>=1.18; extra == 'ml'
Requires-Dist: torch>=2.5; extra == 'ml'
Provides-Extra: onnx
Requires-Dist: onnx>=1.16; extra == 'onnx'
Requires-Dist: onnxruntime>=1.18; extra == 'onnx'
Provides-Extra: platform
Requires-Dist: fsspec>=2024.6; extra == 'platform'
Requires-Dist: pyarrow>=16.0; extra == 'platform'
Requires-Dist: redis>=5.0; extra == 'platform'
Provides-Extra: pyod
Requires-Dist: pyod>=2.0; extra == 'pyod'
Provides-Extra: release
Requires-Dist: build>=1.2; extra == 'release'
Requires-Dist: docutils<0.22,>=0.21.2; extra == 'release'
Requires-Dist: twine<8.0,>=7.0; extra == 'release'
Provides-Extra: storage
Requires-Dist: h5py>=3.10; extra == 'storage'
Requires-Dist: pyarrow>=16.0; extra == 'storage'
Provides-Extra: torch
Requires-Dist: lightning>=2.2; extra == 'torch'
Requires-Dist: torch>=2.2; extra == 'torch'
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.7; extra == 'visualization'
Requires-Dist: plotly>=5.13; extra == 'visualization'
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://anomx.io">
    <picture>
      <img src="assets/logo.png" alt="Anomx logo">
    </picture>
  </a>
</p>

<p align="center">The AI agent for coding, data analysis and anomaly detection.</p>

<p align="center">
    <a href="https://pypi.org/project/anomx/"><img alt="PyPI - Version" src="https://img.shields.io/pypi/v/anomx?style=flat-square&label=pypi" /></a>
    <a href="https://pypi.org/project/anomx/"><img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/anomx?style=flat-square"/></a> 
</p>

[![Anomx Terminal UI](assets/anomx-shot-03.png)](https://anomx.io)

# Anomx

`anomx` is the installable Python foundation of Anomx. It ships both reusable
time-series and anomaly-detection primitives and the `anomx` CLI agent for
interactive anomaly investigation, data analysis, and platform-connected edge
workflows.

The wider Anomx platform handles orchestration, workers, storage, connectors,
audit trails, and human-in-the-loop review. This repository contains the
portable modeling layer plus the operator-facing CLI agent that can run on any
server, workstation, or laptop.

## Goals

- Provide clean primitives for time-series datasets, scorers, detectors, and models.
- Support both batch and online anomaly detection workflows.
- Keep outputs interpretable: scores, thresholds, timestamps, labels, and metadata.
- Ship a practical CLI agent that is tuned for anomaly detection, time-series inspection,
  and data-quality analysis tasks.
- Stay modular enough to power the Anomx platform without coupling the library to the
  platform's storage or orchestration layer.
- Integrate with the broader time-series ecosystem, especially Darts, through optional
  adapters.

## Installation

The package is structured for PyPI distribution:

```bash
pip install anomx
```

For local development:

```bash
git clone https://github.com/anomx/anomx.git
cd anomx
python -m pip install -e ".[dev]"
```

Optional extras:

```bash
pip install "anomx[darts]"     # Darts forecasting model adapters
pip install "anomx[docs]"      # Documentation tooling
pip install "anomx[platform]"  # Platform-facing IO and connector dependencies
pip install "anomx[release]"   # Build and PyPI publishing tooling
```

## Python Quick Start

```python
from anomx import (
    AbsoluteErrorScorer,
    AnomalyPipeline,
    ConstantBaselineModel,
    ObservationSet,
    ThresholdDetector,
)
from anomx.data import make_sine_anomaly_dataset


frame = make_sine_anomaly_dataset().to_dataframe().reset_index()
observation_set = ObservationSet(observations=frame, timestamp_column=str(frame.columns[0]))
pipeline = AnomalyPipeline(
    model=ConstantBaselineModel(),
    scorer=AbsoluteErrorScorer(),
    detector=ThresholdDetector({"source_column": "score", "threshold": 3.0}),
)
pipeline.fit(observation_set)
events = pipeline.detect(observation_set)
print(events.to_dict())
```

## Anomx CLI Agent

Installing the package also installs the `anomx` console command:

```bash
anomx
```

The CLI agent is meant to feel like a modern coding/data agent, but tuned for
anomaly detection, time-series investigation, data quality problems, and
operational analysis.

Useful startup examples:

```bash
anomx --version
anomx --print-home
anomx --provider openai --model gpt-5.5
anomx --provider anthropic --model claude-sonnet-4-6
anomx --provider kimi --model kimi-k3
anomx --ollama --model qwen3-coder:30b
```

Current CLI capabilities include:

- A full-screen terminal UI with persisted transcripts and session history.
- Tool blocks show the latest activity while running and a count-based summary
  when the agent moves on to text. Completed work folds into an expandable
  "Worked for ..." line, leaving the final answer visible. The Extended work
  visualization setting keeps the full transcript open.
- Multiple model backends: OpenAI, Anthropic, Kimi, DESY Assistant, JSC
  Blablador, and local Ollama.
- Five execution modes: Plan, Recommend (with a connected platform), Standard,
  Automatic, and Autonomous.
- Connected-platform skills for integrations, storage browsing, acquisition,
  datasets, jobs, model training, findings, and systems, plus user-defined skills.
- Tool-backed repository and data inspection, with optional subagents for
  focused parallel tasks and a persistent goal mode.
- A small inspectable home directory at `~/.anomx` (or `ANOMX_HOME`) that stores
  config, auth metadata, skills, session transcripts, and a persistent private brain.

On first launch, choose whether tools run directly on your host or in a Docker
or Podman container. Installed engines are selectable; missing engines stay
visible but disabled. Start the chosen engine before using it. You can change
the default later in `/config` → **Manage Sandbox**. Containerized chats show
**Secure Agent Runtime** in the header.

For local host execution, the directory where you launch `anomx` is the task
directory. The CLI home structure looks like this:

```text
~/.anomx/
  config.toml
  auth.json
  skills/<command>/SKILL.md
  skills/<command>/references/
  brain/INDEX.md
  brain/instructions/
  sessions/index.jsonl
  sessions/usage.json
  sessions/<chat-id>/
    session.jsonl
    tmp/
    sub_agents/<name>/
      AGENT.md
```

`brain/` and `skills/` are shared across the user's chats. API and search
responses go in the chat's `tmp/`; each delegated agent gets its own directory.
Every upgraded CLI installation migrates its existing home automatically on startup,
including homes selected through `ANOMX_HOME`; no cleanup command is needed. A versioned
journal makes migration resumable after interruption and prevents repeated history scans,
while a process lock coordinates concurrent launches. Authentication and configuration
stay in place. Existing transcripts and custom instructions move into this layout;
unassigned response/search files are preserved in `sessions/_legacy/tmp/`. Recorded
runtime paths are repaired and historical artifact paths remain readable through the
file tools. Unknown files and conflicting destination files are preserved without
overwriting either version. This migration does not expire or delete old chat content.
If an explicitly configured destination is on another filesystem, the affected legacy
files are kept at their original location instead of blocking startup or deleting them.
Close CLI processes running an older package version before upgrading: they do not
participate in the new migration lock, and any legacy files they recreate are preserved.

Containerized CLI execution uses one container named `anomx-agent`. Opening the CLI
or a chat does not start it; the first submitted message starts it lazily. It stays
running after the CLI exits until you stop it explicitly, for example with
`docker stop anomx-agent` or `podman stop anomx-agent`.

The container exposes `/anomx/brain`, `/anomx/skills`, and `/anomx/sessions/`. Each
session has `session.jsonl`, `tmp/`, `sub_agents/`, and its own `task/` directory,
persisted under the matching `~/.anomx/sessions/<chat-id>/` folder. The launch
folder is **not mounted or copied**. The agent receives its path and a bounded
file listing as context; its file tools and commands start inside the isolated
task folder.

When a task needs host files, the `mount_folder` tool requests explicit read/write
approval for a full absolute folder path, regardless of agent mode. Approvals are
remembered for that task; other tasks need their own approval. The tool returns a
stable path under `/anomx/mounts/`. The host home, filesystem root, Anomx credentials,
and Docker socket are never mounted by default. Runtime data belongs to one user;
the shared container is not a security boundary between that user's chats.

The first message builds a local `anomx-agent-runtime` image with Python, Git,
Node.js, and common analysis tools. This needs network access and can take a few
minutes; subsequent starts reuse it. The image tag includes the installed Anomx
version and recipe/source digest. Docker cannot change bind mounts on a running
container, so changing approved folders, resource limits, or the runtime image
recreates the idle container under the same name. Active commands or background
processes prevent replacement. Mounted data persists; packages installed only in
the container do not survive replacement. No launch-folder files or credentials
are sent to the image builder. Docker Desktop starts automatically on macOS when
needed; elsewhere, start Docker or your Podman machine first. An unavailable
engine produces a retryable setup message, never a switch to host execution.
Platform runtimes retain their chat-specific five-folder workspace layout.

Type `@` to find files. Type `/` to open commands, including chat modes:

- `/subagents Inspect this project` allows delegation. Each child starts from
  `sub_agents/<name>/AGENT.md`, exchanges Markdown messages and results with the
  main agent, and can be asked to continue after completing its task.
- `/goal Complete this task` creates or uses `GOAL.md` in the task/project
  directory. The agent records progress and receives a private completion check
  after each apparent finish. It ends goal mode explicitly with `finish_goal`.
- Use `/subagents:off` or `/goal:off` in a follow-up to disable a feature.

Active features appear below the CLI's execution mode. Intermediate and final
responses appear line by line; typing skips the reveal and keeps your input.

### Platform Connection

When an Anomx Platform instance is available, the CLI can be connected directly
from the agent UI using normal platform credentials. The platform issues a
dedicated CLI-agent token, tracks the CLI host name and client version, and
keeps the machine attached to the same organization context as the platform.

The agent's `brain/` folder persists across sessions and synchronizes with the
same user's cloud agent before and after each turn. It can hold notes, plans, and
supporting files independently of the user's project. Offline edits remain local
until the next successful sync. Concurrent edits preserve a conflict copy instead
of silently overwriting changes. Keep credentials out of notes; sync is private
to the connected account and bounded to 512 paths, 1 MiB per file, and 8 MiB total.

That makes `anomx` the practical edge entry point for working where the data
lives first, then carrying that context back into the platform for visualization,
findings, follow-up jobs, and broader analysis workflows.

## Package Layout

```text
src/anomx/
  agent/         CLI agent and its independent runtime
  base/          Shared metadata, capabilities, signatures, class discovery
  data/          Datasets, base contracts, sources, views, processing
  models/        Base contracts, forecasting, reconstruction, representation
  detection/     Scorers, detectors, pipelines, and inspectable results
  execution/     Local job execution, run tracking, host work interfaces
  integrations/  Optional Darts and platform adapters
```

See [package architecture](docs/architecture.md) for dependency rules and the
migration map. Each domain exports its public objects through `__init__.py`.


## Darts Integration

Use the generic `Dataset` for data access and explicit `.to_darts()` conversion
for Darts models. `PyTorchModel` accepts either representation. See
[flexible jobs and ONNX training](docs/flexible-jobs.md) for a complete starter,
backend channel loading, custom networks, and portable model publication.

```bash
pip install "anomx[ml]"
python examples/flexible_job_training.py
```

The default install stays lightweight. To use Darts models, install the optional
extra and wrap any compatible Darts forecasting model:

```python
from darts.models import ExponentialSmoothing

from anomx.data import make_sine_anomaly_dataset
from anomx.integrations import DartsForecastingModel

dataset = make_sine_anomaly_dataset()
model = DartsForecastingModel(ExponentialSmoothing())
forecast = model.fit(dataset).predict(24)
```

The intent is to let Anomx expose Darts-backed forecasting and anomaly workflows
without making Darts a required dependency for every user.

## Development

```bash
python -m pip install -e ".[dev]"
pytest
ruff check .
mypy src/anomx
python -m pip install -e ".[release]"
python -m build
```

## Platform Context

Anomx prioritizes:

- Signal over noise: surface only relevant insights.
- Clarity over complexity: outputs should be interpretable.
- Actionability: every insight should support a decision.

The platform is designed around modular pipelines, real-time and batch workers,
heterogeneous data sources, and versioned entities such as datasets, channels,
jobs, runs, findings, model artifacts, and node services. This package is the
focused modeling and agent layer used by that larger system.

## Status

This repository is in pre-alpha stage. Public APIs and CLI ergonomics should be
treated as provisional until the first stable release.

## Runs and workspaces

Use `anomx.init(project="experiment")` and `anomx.log("loss", value)` for portable,
step-based execution tracking. See [Runs and workspace editing](docs/runs.md) for
offline logging, platform delivery, hosted jobs, retries, and multi-file editing.
