Metadata-Version: 2.4
Name: virgofash
Version: 0.2.0
Summary: Local-first deterministic asynchronous search and answer engine
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Dynamic: license-file

# VirgoFash Advanced

VirgoFash is a local-first deterministic Python search and answer engine.

## Important

VirgoFash does **not** use an LLM, AI model, OpenAI/Gemini API, or paid API.

It produces answers using:
- deterministic NLP
- built-in knowledge
- concurrent web search
- result ranking
- snippet extraction
- duplicate removal
- deterministic response templates

So it can produce an LLM-like *experience* for supported tasks, but it is not a real language model.

## Requirements

- Python 3.10+
- Internet connection for web search
- `httpx`
- `pytest`
- `pytest-asyncio`

## Project structure

```text
virgofash/
├── __init__.py
├── __main__.py
├── answer.py
├── core.py
├── exceptions.py
├── knowledge.py
└── nlp.py

tests/
├── test_answer.py
└── test_core.py
```

## 1. Install

From the project root:

```powershell
python -m pip install -e .
python -m pip install pytest pytest-asyncio httpx
```

## 2. Run tests

```powershell
python -m pytest -q
```

Expected: all tests pass.

## 3. Test one question

```powershell
python -c "import asyncio; from virgofash import ask; r=asyncio.run(ask('What is AI?')); print(r.answer)"
```

## 4. Interactive mode

This is the easiest way to use VirgoFash:

```powershell
python -m virgofash
```

Then:

```text
You: hello
VirgoFash: Hello! How can I help you?

You: What is AI?
VirgoFash: ...

You: What is Python?
VirgoFash: ...

You: What is FastAPI?
VirgoFash: ...

You: exit
```

## 5. Web-search question

For questions not in the built-in knowledge base, VirgoFash searches its providers:

```text
You: What happened in ...
```

The answer is built from returned search snippets. Provider failures are isolated.

## 6. Python API

```python
import asyncio
from virgofash import ask

result = asyncio.run(ask("What is FastAPI?"))

print(result.answer)

for source in result.sources:
    print(source.title)
    print(source.url)
```

## 7. What this project can and cannot do

### Can
- answer common built-in definitions
- detect greetings/questions/search queries
- search multiple providers concurrently
- rank and deduplicate results
- construct deterministic summaries from snippets
- expose a clean Python API
- run as an interactive terminal assistant

### Cannot
- reason like a neural language model
- reliably understand every natural-language question
- generate arbitrary original explanations with LLM-level fluency
- guarantee provider availability
- replace a real LLM

## Troubleshooting

### `ImportError: cannot import name 'ask'`

Make sure `virgofash/__init__.py` contains:

```python
from .answer import AnswerEngine, AnswerResponse, AnswerSource, ask
```

### PowerShell accidentally receives Python code

Do not paste Python source directly into PowerShell. Put Python code inside `.py` files. PowerShell is for commands such as:

```powershell
python -m pytest -q
python -m virgofash
```

### Internet provider failure

A provider may fail because of network restrictions, rate limits, HTML changes, or temporary downtime. VirgoFash records failed providers instead of crashing the whole aggregation.

## License

MIT
