Metadata-Version: 2.4
Name: omniscout
Version: 0.3.2
Summary: OmniScout CLI: local-first multi-browser automation, semantic search, and research for AI agents
Project-URL: Homepage, https://omniscout.xyz
Project-URL: Repository, https://github.com/sriramramnath/omniscout
Project-URL: Documentation, https://docs.omniscout.xyz
Project-URL: Changelog, https://github.com/sriramramnath/omniscout/blob/main/cli/CHANGELOG.md
Project-URL: Issues, https://github.com/sriramramnath/omniscout/issues
Author: OmniScout
License: Modified MIT License
        
        Copyright (c) 2026 OmniScout
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        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.
        
        Our only modification part is that, if the Software (or any derivative works
        thereof) is used for any of your products or services, you shall prominently
        display "Powered by OmniScout" on the user interface of such product or
        service.
License-File: LICENSE
Keywords: agent,cli,playwright,research,scraping,search
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9
Requires-Dist: httpx>=0.27
Requires-Dist: markdownify>=0.13
Requires-Dist: nltk>=3.8
Requires-Dist: platformdirs>=4.2
Requires-Dist: playwright>=1.45
Requires-Dist: pydantic>=2.7
Requires-Dist: qdrant-client>=1.9
Requires-Dist: rich>=13.7
Requires-Dist: selectolax>=0.3.21
Requires-Dist: sentence-transformers>=2.7
Requires-Dist: sumy>=0.11
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: torch>=2.2
Requires-Dist: trafilatura>=1.12
Requires-Dist: transformers>=4.40
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: train
Requires-Dist: accelerate>=0.30; extra == 'train'
Requires-Dist: datasets>=2.19; extra == 'train'
Requires-Dist: peft>=0.11; extra == 'train'
Requires-Dist: trl>=0.9; extra == 'train'
Description-Content-Type: text/markdown

<div align="center">

# OmniScout

**Local-first browser automation, semantic search & research for AI agents.**

No cloud APIs. No hosted sessions. No lock-in. Just a fast, local HTTP daemon in your terminal.

![Terminal](./assets/demo-terminal.png)

![Python 3.11+](https://img.shields.io/badge/python-%3E%3D3.11-4584d3?style=flat-square&logo=python&logoColor=white)
![License](https://img.shields.io/badge/license-Modified%20MIT-393939?style=flat-square)

[Docs](https://docs.omniscout.xyz) · [Website](https://omniscout.xyz)

</div>

```bash
pip install omniscout
omniscout install --skill            
omniscout install --probe-0-mini

```

---

## What It Is

OmniScout is a self-contained **terminal-native interface for the web**. Think of it as a local browser brain for AI agents — enabling them to search, browse, extract structured data, and remember everything without ever leaving your laptop.

A long-lived daemon at `127.0.0.1:7720` provides sub-second browser actions, a warm embedding model, and a local vector store. It communicates entirely over HTTP/JSON and works with your existing Chromium browser (Chrome, Brave, Edge, Vivaldi, etc.).

---

## Why OmniScout?

| Feature | Status |
| :--- | :--- |
| **Local First** | No API keys, no remote browsers, no data leaving your laptop |
| **Semantic Search** | Searches the web and re-ranks results using local sentence-transformers embeddings |
| **Long-lived Daemon** | Sub-second per-action latency with persistent sessions |
| **Real Browser** | Drives your real Chrome/Brave; keeps cookies, logins, and extensions |
| **Semantic Memory** | Remember and search your browsing history with vector embeddings |
| **Rich Extraction** | Pull structured data from any URL with zero LLM calls |
| **Agent-Ready** | Every command speaks JSON — hook it up to any AI framework |

---

## Install

```bash
# One-liner: installs pip, browser, models, and agent skill
curl -fsSL https://omniscout.xyz/install.sh | bash
```

# Quick Start

After running all the commands, just type /omniscout into any agent—such as Codex, Claude, Code, Cursor, or any other coding agent—and type away in natural language. It will use Omniscout to search, extract, and close the browser, with no technical knowledge needed. That’s it.

If you want to know how it works and how to use it manually without AI agents, you can read below.

## Core Commands

### 1. Search & Research

```bash
# Semantic web search
omniscout search "state of local AI agents 2026"

# Summarized one-sentence answer (no LLM)
omniscout answer "Who is the president?" --depth balanced

# Full research pipeline (search → crawl → extract → rerank → summarize)
omniscout research "emerging quantum computing startups 2026"
```

### 2. Browser Automation

```bash
# Navigate and identify elements with accessibility tree refs
omniscout browser navigate https://news.ycombinator.com
omniscout browser snapshot --refs-only
omniscout browser click '@e3'

# Screenshots (full page, delayed, or centered)
omniscout browser screenshot --full-length --out state.png
omniscout browser screenshot --delay 2 --out after-load.png

# Capture network and console logs
omniscout browser network list
omniscout browser console tail
```

### 3. Content Extraction

```bash
# Clean Markdown or structured JSON from any page
omniscout extract https://example.com
omniscout extract -q "SpaceX founder" --format structured --fields founder

# Exa-style schema-driven extraction (no LLM)
omniscout extract https://stripe.com/pricing \
  --schema-inline '{"type":"object","properties":{"pricing":{"type":"string"}}}'
```

### 4. Knowledge Graphs

```bash
# Map a company or person into a structured Unicode tree
omniscout graph "Cursor"              # search web and extract
omniscout graph "Cursor" -w cursor.com --data  # crawl site directly
omniscout graph "Cursor" --llm        # optional LLM overlay on evidence
```

### 5. Browser Memory

```bash
# Remember and semantically search your browsing history
omniscout remember https://example.com/blog/post
omniscout memory "neural networks in production"
```

---

## Architecture

The tool is split between a thin CLI (Typer + Rich) and a robust HTTP daemon that handles the heavy lifting.

```
┌──────────────────┐                                       ┌────────────────────────────────────┐
│   OmniScout CLI  │       ┌──────────────────────────────────┤     OmniScout Daemon               │
│  (typer + rich)  │-------│    HTTP POST /command            │   (127.0.0.1:7720)                 │
└──────────────────┘       │                                   │       ┌─ Playwright Backend          │
        │                 │                                   │       ├─ Extension Backend (opt-in)│
        v                 │                                   │       └─ Embed Service (warm model)│
   Search / Extract -------│                                   └────────────────────────────────────┘
   / Research engines ----─┘
```

For contributors:

```
cli/omniscout/
  app.py              # Typer root
  commands/           # CLI subcommands
  daemon/             # HTTP server, backends, replay
  engines/            # browser, search, research, extractor, crawler
  store/              # SQLite cache, sessions, workflow, memory
  models.py           # Pydantic JSON contracts
```

---

## JSON & Agent Integration

Every command speaks JSON. Set `OMNISCOUT_JSON=1` and `stdout` becomes a structured payload.

```bash
export OMNISCOUT_JSON=1
omniscout search "robotics simulators"
```

Or talk to the daemon directly:

```bash
curl -X POST http://127.0.0.1:7720/command \
  -H 'Content-Type: application/json' \
  -d '{"action":"navigate","args":{"url":"https://example.com"},"session":"demo"}'
```

---

## Configuration

Create a `config.toml` in your config directory (e.g. `~/.config/omniscout/config.toml` on Linux, `~/Library/Application Support/omniscout/config.toml` on macOS):

```toml
default_source = "ddg"
search_limit = 10
research_results = 8
request_throttle_seconds = 1.0
embedding_model = "sentence-transformers/all-MiniLM-L6-v2"
browser = "chrome"                    # chrome | edge | brave | vivaldi | opera | arc | chromium | custom
# browser_executable = "/path/to/browser"  # only needed for 'custom'
```

Or configure via CLI:

```bash
omniscout settings browsers
omniscout settings set browser brave
omniscout settings show
```

### Environment Variables

| Variable | Purpose |
| --- | --- |
| `OMNISCOUT_JSON=1` | Force JSON output on every command |
| `OMNISCOUT_DAEMON_AUTO_START=0` | Don't auto-start the daemon |
| `OMNISCOUT_DAEMON_PORT` | Daemon port (default: 7720) |
| `OMNISCOUT_DATA_DIR` | Override the default data directory |
| `OMNISCOUT_BROWSER` | Browser ID (overrides config) |
| `OMNISCOUT_EMBED_LOCAL_ONLY=0` | Allow runtime Hugging Face fetches |
| `TWOCAPTCHA_API_KEY` | CAPTCHA solver API key |

Legacy `HARNESS_*` equivalents accepted.

---

## On-disk State

| Path | Purpose |
| --- | --- |
| `profiles/` | Persistent Chrome user-data-dirs |
| `qdrant/` | Embedded vector index |
| `models/sentence-transformers/` | Prefetched embedding model |
| `memory.sqlite` | Browser memory (visits + notes) |
| `sessions.sqlite` | Long-lived browser session registry |
| `cache/pages/` | Content-hashed HTML cache |
| `daemon/` | PID, port, logs, action history, session restore |

---

## License

Modified MIT — see [LICENSE](LICENSE). Products built on OmniScout must prominently display **Powered by OmniScout** on the user interface.
