Metadata-Version: 2.4
Name: atomzero
Version: 0.1.2
Summary: Atom Zero: a local source-cited 49.2M assistant with RAG, documents, evidence and constrained tools.
Author-email: Gokhan Cava <gokhancava@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/byjameson/stream-finetune
Project-URL: Issues, https://github.com/byjameson/stream-finetune/issues
Project-URL: LinkedIn, https://www.linkedin.com/in/g%C3%B6khan-cava-874a32157/
Keywords: atom-zero,local-assistant,rag,source-citation,small-language-model,pypdf
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: torch
Requires-Dist: tokenizers
Requires-Dist: numpy
Requires-Dist: pypdf>=4
Requires-Dist: python-docx>=1.1
Provides-Extra: neural
Requires-Dist: transformers>=4.40; extra == "neural"
Dynamic: license-file

# Atom Zero 49.2M — a local assistant that cites its sources

Atom Zero is a local, source-cited assistant built around a **49.2M parameter
model trained from scratch**. Facts live in a local RAG index, not in the model
weights; the model handles wording and behavior while deterministic tools,
documents, memory and citations do the rest.

This is the standalone `atomzero` package. The low-VRAM trainer remains in the
separate [`streamft`](https://pypi.org/project/streamft/) package.

## Install

```powershell
pip install atomzero==0.1.2
```

Optional local MiniLM reranker:

```powershell
pip install "atomzero[neural]"
```

The model weights are not bundled. Download them from
[Hugging Face](https://huggingface.co/byjameson/atom-zero-49m) or
[ModelScope](https://modelscope.cn/models/byjameson/atom-zero-49m).

## Quickstart

```powershell
atomzero-quickstart
```

The first run downloads the ~197 MB checkpoint/tokenizer, seeds a demo corpus
and opens the local UI. No streamft checkout is needed. Use `--provider` to
route free-form chat to local Ollama while RAG/tools stay local.

## Manual run

```powershell
atomzero `
  --model checkpoints/transformer_behavior_50m_scaled `
  --tokenizer data/chat_en_bpe8k.json `
  --docs data/docs.db
```

Then open the local page (default `http://127.0.0.1:8013`).

## Features

- **PDF, DOCX, HTML and Markdown ingestion** with page/section citations.
- **Evidence API/panel** that opens the exact local chunks behind a citation.
- **Deterministic tools**: time, safe arithmetic, tasks, name/likes memory.
- **Constrained plan API** (`/v1/agent/plan`): allowlist, three-step cap and
  explicit confirmation for task/research side effects.
- **Sessions**: transcript restore, export/import, exact Forget.
- **Research queue**: approved-only Wikipedia fetch and local teacher notes.
- **Optional local provider**: Ollama/OpenAI-compatible free-form chat while RAG,
  tools and memory stay local.
- **No telemetry** and no hosted service.

## Honest limits

- The raw 49.2M model scores **2/10** on the no-RAG knowledge probe.
- The product scores **21/21** on the narrow authored product benchmark because
  RAG and tools do the work.
- The core context is **128 tokens**; it is not a general reasoning or coding
  model.
- No OCR; scanned PDFs need OCR before ingestion.
- Safety is optional and off by default.

## Links

- Full project map: <https://github.com/byjameson/stream-finetune/blob/main/docs/PROJECT_OVERVIEW.md>
- Documents/citations: <https://github.com/byjameson/stream-finetune/blob/main/docs/DOCUMENTS.md>
- Tool plans: <https://github.com/byjameson/stream-finetune/blob/main/docs/TOOL_PLANNING.md>
- Benchmarks: <https://github.com/byjameson/stream-finetune/blob/main/docs/BENCHMARKS.md>
- Model card: <https://huggingface.co/byjameson/atom-zero-49m>
- Contact: **gokhancava@gmail.com**

Apache-2.0 for code and weights; data attribution in `NOTICE`.
