Metadata-Version: 2.4
Name: vierrataleai
Version: 0.1.0b9
Summary: VierrataleAI - Intelligent terminal assistant
Author: Vierratale
License: MIT
Keywords: ai,chatbot,terminal,assistant,llm
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: rich>=13.0
Dynamic: requires-python

# VierrataleAI

Intelligent terminal assistant that runs AI models locally and in the cloud.

## Install

```bash
pip install vierrataleai
```

The first launch detects and, if needed, installs and starts the local engine
(**Cortex** - "secretly" Ollama under the hood), then pulls the model you use.

## Usage

```bash
vierrataleai                          # Start chat (auto-detect provider)
vierrataleai --provider cortex        # Use local models
vierrataleai --provider openai        # Use cloud models (OpenAI)
vierrataleai --provider anthropic     # Use cloud models (Claude)
vierrataleai --provider gemini        # Use cloud models (Gemini)
vierrataleai --model VRTL-6.pro   # Use specific model

# Or run as module
python -m vierrataleai
```

## Models

Local models run through the **Cortex** engine:

| Model | Backend |
|-------|---------|
| VRTL-1.lite | qwen3:0.6b |
| VRTL-2.fast | gemma3:1b |
| VRTL-3.small | llama3.2:1b |
| VRTL-4.balanced | qwen2.5:1.5b |
| VRTL-5.plus | qwen3:1.7b |
| VRTL-6.pro | qwen2.5:3b |

Cloud models are available when the matching provider + API key is configured:

| Model | Backend |
|-------|---------|
| VRTL-7.cloud-mini | gpt-4o-mini (OpenAI) |
| VRTL-8.cloud | gpt-4o (OpenAI) |
| VRTL-9.cloud-fast | claude-3-5-haiku-20241022 (Anthropic) |
| VRTL-10.cloud-pro | claude-sonnet-4-20250514 (Anthropic) |
| VRTL-11.cloud-lite | gemini-2.0-flash (Gemini) |
| VRTL-12.cloud-plus | gemini-1.5-pro (Gemini) |

> Legacy `vierratale-*` model names (e.g. `vierratale-fast`, `vierratale-cloud`) still work and are stored as VRTL names.

## Commands

- `/help` - Show commands
- `/model [name]` - Switch model
- `/provider [name]` - Switch provider
- `/models` - List available models
- `/system [text]` - Set a custom system prompt / persona
- `/search <query>` - Search the web and summarize with AI
- `/fetch <url>` - Open a link and summarize its content
- `/log [n|path]` - Show the last n log entries (default 30) or the log file path
- `/clear` - Clear screen
- `/new` - Start a new conversation (clear memory)
- `/quit` - Exit

## Smart Search

Asking a question (Who/What/When/Where/Why/How...?) automatically searches the
web and summarizes the results with AI. Bare mentions of specific topics also
trigger a search — e.g. `timun mas from indonesia`, `the legend of roro
jonggrang`. For example:

```
> Who is Cristiano Ronaldo?
> timun mas from indonesia
```

triggers a live web search and answers from the results. If no web results come
back, the AI answers from its own knowledge instead of going quiet. Use
`/search <query>` to force a search explicitly.

Story requests about any subject work the same way — no matter how they're
phrased (`a story about X`, `the legend of X`, `tell me about X`, `narrate the
tale of X`, `write X into a txt file`). The subject is pulled out of the
sentence, searched first, and the reply is saved to a `<subject>.txt` file.
A generic `tell me a story` (no subject) is told directly from the model — and
is also saved to a `.txt` file.

Greetings (`hi`, `hello`, `hey`, `good morning`, ...) are answered instantly
with a short fixed reply — they never reach the model.

## Writing Files

Ask the AI to create code, configs, scripts, web pages, or a whole project. When it
responds, it lists each file with a `FILE: <path>` header followed by a code
fence (and `FOLDER: <path>` for empty folders) — just running in the chat writes
them to your disk in the current working directory. Any file type is supported,
including JSON config files and HTML pages. Nested folders are created automatically, existing
files are skipped unless you confirm to overwrite, and nothing is ever written
outside the working directory.

If the AI ever answers with the code but forgets the `FILE:` header (or writes an
HTML page without a fence), the assistant rescues it: any `FILE: <path>` line in
the reply is honored even without a fence, otherwise the request is used to
infer a filename and the code block is saved anyway. Filename inference covers
many formats, not just web pages:

| Request contains… | Saved as |
|--------------------|----------|
| `html` / `webpage` / `website` / `page` | `index.html` |
| `css` | `style.css` |
| `python` / `py` | `script.py` |
| `flask` / `django` / `fastapi` / `streamlit` / `app` | `app.py` |
| `javascript` / `js` / `script` | `script.js` |
| `typescript` / `ts` | `script.ts` |
| `bash` / `zsh` / `shell` | `script.sh` |
| `json` / `yaml` / `yml` / `csv` / `sql` | `output.json` / `.yml` / `.csv` / `.sql` |

When the request has no hint at all, the fence language in the reply picks the
name (```python → `script.py`, ```css → `style.css`, …). Saving also kicks in
whenever the reply itself contains a `FILE:`/`FOLDER:` line, or when a reply is
basically just one substantial code block, even if the request phrasing wasn't
matched.

For file requests, a short format instruction is silently attached to your
message so the model emits complete `FILE:` blocks with closed fences. And if
the model ever answers a file request *without any code* (free-style prose,
interrupted before a fence), nothing is saved and you get a notice telling you
to ask again — a `.py` file full of chatter is never created.

Example of what the AI emits:

```
FILE: config.json
```json
{
  "name": "my-app",
  "port": 3000
}
```

FILE: index.html
```html
<!doctype html>
<html><body>Hello</body></html>
```

FILE: src/hello.py
```python
print('Hello VierrataleAI')
```

## Chat UI

The chat runs in a clean, minimal full-screen interface: your turns are labelled
`You` and the assistant's `AI`, with plain wrapped text in between. Code blocks
are the exception — they render inside a green bordered box with their language
tag (`╭─ html ─╮`), so files stand out at a glance. The latest reply stays pinned
to the bottom of the terminal while it streams in (no screen flashing), and
internal search/fetch context stays hidden.

## Automatic Logging

Everything that happens in a session is written automatically to a per-day log
file in `~/.config/vierrataleai/logs/` (e.g. `vierrataleai-20260101.log`):
app/session start, every user message, every AI reply, every file write or
skip, and any errors — with a timestamp. The logs are plain text and safe to
grep. To inspect them from inside the chat:

```
/log          # show the last 30 entries
/log 100      # show the last 100 entries
/log path     # print the log file path
```

## Conversation Memory

Your conversation is saved automatically and restored on the next launch, so
you can continue where you left off. Use `/new` to start fresh.

## Configuration

Config file: `~/.config/vierrataleai/config.json`

Environment variables:
- `VIERRATALE_PROVIDER` - Default provider (auto/cortex/openai/anthropic/gemini)
- `VIERRATALE_MODEL` - Default model
- `OPENAI_API_KEY` - OpenAI API key (openai provider)
- `ANTHROPIC_API_KEY` - Anthropic API key (anthropic provider)
- `GEMINI_API_KEY` - Google AI API key (gemini provider)

## Build Standalone Binary

```bash
./build.sh
# Output: dist/vierrataleai
```

## License

MIT
