Metadata-Version: 2.4
Name: evidion
Version: 3.0.1
Summary: Open Research Intelligence for the terminal
Author: Evidion contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/EvidionAI/evidion
Project-URL: Repository, https://github.com/EvidionAI/evidion
Project-URL: Issues, https://github.com/EvidionAI/evidion/issues
Project-URL: Changelog, https://github.com/EvidionAI/evidion/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/EvidionAI/evidion/security/policy
Keywords: ai,agent,research,cli,search,sources,citations,searxng,markdown,terminal
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: keyring<25,>=24.3
Dynamic: license-file

# EVIDION

**Plan-first AI research for people who want sources, not guesses.**

[![PyPI version](https://img.shields.io/pypi/v/evidion.svg)](https://pypi.org/project/evidion/)
[![Python versions](https://img.shields.io/pypi/pyversions/evidion.svg)](https://pypi.org/project/evidion/)
[![Tests](https://github.com/EvidionAI/evidion/actions/workflows/tests.yml/badge.svg)](https://github.com/EvidionAI/evidion/actions/workflows/tests.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Evidion is a free, open-source terminal research assistant. It shows a
research plan before it searches, lets you approve or change that plan, then
saves a local, source-linked research trail and report.

![Terminal demo](https://raw.githubusercontent.com/EvidionAI/evidion/main/docs/demo.svg)

## Why Evidion?

- It shows the research plan before searching.
- It keeps a local session trail of sources, claims, and open gaps.
- It separates source-reported claims from independently verified facts.
- It works from the terminal and can use your own SearXNG instance.
- It exports portable Markdown, text, HTML, and JSON reports.

## Install

Evidion supports Python 3.8 or newer on macOS, Windows, and Linux.

```bash
python3 -m pip install --user evidion
evidion doctor
```

Start Evidion from any directory:

```bash
evidion
```

If the command is not found, add Python's user scripts directory to your
`PATH`. Common locations are `$HOME/.local/bin` on Linux,
`$HOME/Library/Python/3.9/bin` on macOS, and the Python `Scripts` directory
under `%APPDATA%` on Windows.

## Quick start

Web research needs a SearXNG instance with JSON output. Configure it once:

```bash
evidion config set --searxng-url http://localhost:8080
evidion research "Are local AI models useful for small companies?" --mode normal
```

Evidion displays the plan first. Press Enter to approve, write `add` to add
constraints such as “focus on Switzerland”, or write `cancel` before any web
search happens.

## What it does today

1. Proposes a research plan before searching.
2. Searches a SearXNG instance you control.
3. Safely reads public HTML; private/local addresses, unsafe redirects, and
   non-HTML responses are blocked.
4. Saves sources, source-reported statements, possible conflicts, gaps, and
   the approved plan in a resumable local session.
5. Exports Markdown, text, HTML, and JSON reports.
6. Includes configuration for local and API-backed model providers. Provider
   workflows are early-stage and may change.

## Example output

```text
Research complete
  Sources discovered:  8
  Claims extracted:    21
  Possible conflicts:  2

  Reports saved:
    Markdown  ~/Documents/Evidion/Reports/report.md
    HTML      ~/Documents/Evidion/Reports/report.html
    JSON      ~/Documents/Evidion/Reports/sources.json
```

## Privacy and safety

- Search queries go only to your configured SearXNG instance.
- Web content is treated as untrusted data, never as instructions.
- The reader refuses local/private addresses, unsafe redirects, unsupported
  protocols, and non-HTML content.
- API keys are not stored in research sessions or reports.

See [SECURITY.md](SECURITY.md) and [docs/security.md](docs/security.md).

## Limitations

Evidion does not verify truth automatically. It extracts and compares
source-reported claims; human review remains necessary. Search coverage,
source quality, and model output depend on your configuration.

## Project status

Evidion is early-stage **alpha** software. It is useful for controlled
research experiments, but APIs, provider support, and report formats may
change between releases.

## Roadmap

- [x] Plan-first CLI workflow
- [x] SearXNG search and safe HTML reader
- [x] Local sessions and Markdown/JSON exports
- [x] Local and API-backed provider configuration
- [ ] Additional search providers (for example Tavily or Exa)
- [ ] Browser-based extraction
- [ ] Source-credibility signals
- [ ] Community source scanning

## Comparison

| Tool | Best for | Difference |
| --- | --- | --- |
| ChatGPT | Conversation and drafting | No local research-session or source pipeline by default. |
| Perplexity | Fast web answers | Less direct control over the research plan. |
| Evidion | Terminal research workflows | Plan-first approval, local reports, and a source trail. |

## Commands at a glance

| Command | What it does |
| --- | --- |
| `evidion plan "QUESTION"` | Shows a plan only; it never searches the web. |
| `evidion research "QUESTION"` | Shows a plan, waits for approval, researches, and writes reports. |
| `evidion doctor` | Checks the configured provider and SearXNG setup. |
| `evidion providers` | Lists local and API-backed model providers. |
| `evidion models openrouter --free` | Lists currently free OpenRouter models. |
| `evidion sessions` | Lists saved research sessions. |

See [the command guide](docs/commands.md) and [provider guide](docs/providers.md).

## Development

```bash
git clone https://github.com/EvidionAI/evidion.git
cd evidion
python3 -m pip install -e .
python3 -m unittest discover -s tests -v
```

Older source releases stay available through their Git tags, for example:

```bash
python3 -m pip install --user "git+https://github.com/EvidionAI/evidion.git@v1.0.0"
```

## Where files are stored

Reports and sessions default to `~/Documents/Evidion/`. Configuration is
platform-native: macOS uses `~/Library/Application Support/Evidion`, Windows
uses `%APPDATA%\\Evidion`, and Linux uses `$XDG_CONFIG_HOME/evidion` (or
`~/.config/evidion`). `EVIDION_HOME` and `EVIDION_CONFIG` override these.

## Name and independence

Evidion is an independent open-source project and is not affiliated with
similarly named commercial products or services.

## Contributing

Issues and pull requests are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md),
the [Code of Conduct](CODE_OF_CONDUCT.md), and the
[architecture overview](docs/architecture.md).

## License

[MIT](LICENSE)
