Metadata-Version: 2.4
Name: junio
Version: 0.1.0a2
Summary: Conversational CLI agent that composes academic literature reviews from a workspace folder of papers, with sentence-level citation grounding.
Author-email: Yuan Zongjian <43995742+YuanZongjian@users.noreply.github.com>
License: Copyright (c) 2026 Yuan Zongjian
        All rights reserved.
        
        This software is private and proprietary. No permission is granted to use,
        copy, modify, merge, publish, distribute, sublicense, or sell copies of this
        software, in whole or in part, without the express prior written consent of
        the copyright holder.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: academic,agent,glm,literature-review,llm,rag,research
Classifier: Private :: Do Not Upload
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: <3.13,>=3.11
Requires-Dist: arxiv>=2.1.0
Requires-Dist: cryptography==48.0.1; sys_platform == 'darwin' and platform_machine == 'x86_64'
Requires-Dist: cryptography==49.0.0; sys_platform != 'darwin' or platform_machine != 'x86_64'
Requires-Dist: docx2pdf>=0.1.8; sys_platform == 'win32' or sys_platform == 'darwin'
Requires-Dist: dolphinos
Requires-Dist: httpx>=0.27.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: openai==2.53.0
Requires-Dist: prompt-toolkit>=3.0.43
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pypdf>=4.0.0
Requires-Dist: python-docx>=1.1.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.7.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# junio

A conversational CLI agent that composes academic literature reviews from a
workspace folder of papers — with sentence-level citation grounding and a
verifier that checks every claim against the actual source passage.

Built on the [OpenAI Agents Python SDK](https://openai.github.io/openai-agents-python/),
defaulting to [GLM-5.2](https://open.bigmodel.cn) (Zhipu) for chat and
`embedding-3` for embeddings — both accessed via the
[dolphinos](https://github.com/dolphinquant/dolphinos) model registry and keyed
by `ZHIPU_KEY`. Chat model can be toggled to Kimi via `/model`.

## What it does

1. You drop PDF/DOCX papers into a workspace folder.
2. You run `junio` in your IDE terminal.
3. You converse with the agent: *"Compose a review on retrieval-augmented generation, ~5000 words"*.
4. The agent drafts an outline, composes each section in parallel, runs a
   verifier on every claim against the actual paper passages, and renders
   the result as `report.docx` and `report.pdf`.
5. You give feedback in the REPL: *"Section 3 should be more critical"* —
   the agent revises that section and re-renders.
6. Conversation persists across `junio` invocations in the same
   workspace, so you can pick up where you left off.

## Status

Alpha. First prototype is functional end-to-end on a small fixture corpus.

## Quick start

```bash
pip install -e .                # from a clone
cd ~/projects/my-review
mkdir -p papers
cp ~/Downloads/*.pdf papers/
junio
```

### API key

junio is env-first (12-factor): it reads `ZHIPU_KEY` from the environment.
Get a key at <https://open.bigmodel.cn/usercenter/apikeys>. Provide it any one
of these ways (highest precedence first):

```bash
doppler run -p junio -c dev -- junio   # inject from Doppler — works from any workspace
export ZHIPU_KEY=xxxxxxxx.xxxxxxxx      # shell env, or a workspace `.env` (see .env.example)
junio                                   # …or just run it: the first-run wizard prompts once
```

Doppler is the fleet's central secret store (`doppler login` once; this repo's
`doppler.yaml` pins `project: junio` / `config: dev`, so inside the repo plain
`doppler run -p junio -c dev -- junio` works after `doppler setup`). Store
`ZHIPU_KEY` in the junio project's `dev` config. See dolphinquant/qorka's
`docs/secrets-doppler.md`. Nothing secret is committed — `.env` is gitignored.

> **Dormant fallback:** set `QORKA_GLM_PROVIDER=openrouter` to route chat through
> OpenRouter instead of Zhipu direct. This env var is owned by
> [dolphinos](https://github.com/dolphinquant/dolphinos) — see its docs for the
> required companion key.

## Workspace layout

```
<workspace>/
├── papers/           user drops PDF/DOCX here (auto-discovered)
├── template.docx     optional — overrides built-in templates
├── junio.toml        optional — language, citation style, defaults
├── .junio/           agent-managed state (gitignore'd)
│   ├── cache/        parsed text + embeddings
│   ├── session.db    conversation state (resumable)
│   ├── sandbox/      temp scripts for run_python tool
│   └── runs/<ts>/    every render archived
├── report.docx       latest output
└── report.pdf        latest output
```

## CLI flags

| Flag | Effect |
|---|---|
| `--workspace <path>` | Override workspace (default: cwd) |
| `--fresh` | Delete `.junio/session.db` and start over |
| `--no-resume` | Don't auto-load previous session, but don't delete it |
| `--lang {en,zh,auto}` | Override language detection |
| `--cite {apa,ieee,chicago,gb7714}` | Override citation style |
| `--config <toml>` | Use alternate config file |
| `--debug` | Verbose logging |

## License

Private and proprietary — all rights reserved. See `LICENSE`.

## Design

See `docs/superpowers/specs/2026-04-30-literature-review-agent-design.md`
for the architecture spec.
