Metadata-Version: 2.4
Name: veroq
Version: 2.2.0
Summary: VeroQ Python SDK — the verified intelligence layer for AI agents.
Project-URL: Homepage, https://veroq.ai
Project-URL: Documentation, https://veroq.ai/docs
Project-URL: Repository, https://github.com/veroq/veroq-python
Project-URL: Bug Tracker, https://github.com/veroq/veroq-python/issues
Project-URL: Changelog, https://veroq.ai/docs/changelog
Author-email: VEROQ <dev@veroq.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,api,financial,intelligence,nlp,sdk,truth,verified,veroq
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: requests>=2.20
Provides-Extra: async
Requires-Dist: httpx>=0.24; extra == 'async'
Description-Content-Type: text/markdown

# veroq

**Verified AI. One function call.** Stop shipping hallucinations.

Official Python SDK for [VeroQ](https://veroq.ai). `shield()` any LLM output — every claim fact-checked with evidence chains, confidence scores, and verification receipts.

> Migrating from `polaris-news`? Drop-in replacement — just change your import.

## Prompt Shield — One Line to Verify Any LLM

```python
from veroq import shield

result = shield("NVIDIA reported $22B in Q4 revenue")
print(result.trust_score)      # 0.73
print(result.is_trusted)       # False — claims contradicted
print(result.corrections)      # [{"claim": "...", "correction": "actual revenue was $68B"}]
print(result.verified_text)    # text with corrections inline
print(result.receipt_ids)      # ["vr_abc123"] — permanent proof
```

Works with any LLM. One function. Every claim fact-checked.

## Installation

```bash
pip install veroq
```

## Quick Start

```python
from veroq import VeroqClient

client = VeroqClient()  # uses VEROQ_API_KEY env var

# Ask anything — routes to 41 intents automatically
answer = client.ask("How is NVDA doing?")
print(answer["summary"])
print(answer["trade_signal"])  # { action: "hold", score: 55 }

# Verify any claim — evidence chains + confidence breakdown
result = client.verify("NVIDIA beat Q4 earnings by 20%")
print(result["verdict"])          # "supported"
print(result["confidence"])       # 0.92
print(result["evidence_chain"])   # [{ source: "Reuters", ... }]

# Stream in real-time
for event in client.ask_stream("AAPL price and technicals"):
    if event["type"] == "summary_token":
        print(event["data"]["token"], end="", flush=True)
```

## Multi-Agent Workflows

```python
# Verified Swarm — 5 agents with automatic verification
swarm = client.create_verified_swarm(
    "Analyze NVDA for a long position",
    roles=["planner", "researcher", "verifier", "critic", "synthesizer"],
    escalation_threshold=75,
    credit_budget=30,
)
print(swarm["synthesis"]["summary"])
print(swarm["budget"])                # { spent: 12, remaining: 18 }
print(swarm["verification_summary"])  # { avg_confidence: 82 }

# Domain-specific runtime
legal = client.create_runtime(
    "GDPR data retention requirements",
    vertical="legal",
    cost_mode="premium",
)
```

## External Tool Calls

```python
result = client.call_external_tool("alphavantage", "get_quote", {"symbol": "NVDA"})
# Permission engine → rate limiter → cache → execution → audit
```

## Self-Improvement Feedback

```python
client.submit_feedback(
    session_id=swarm["session_id"],
    query="NVDA analysis",
    reason="data_gap",
    detail="Missing Q4 insider trading data",
)
```

## Enterprise Features

```python
client.configure_enterprise({
    "enterprise_id": "acme-capital",
    "escalation_threshold": 80,
    "escalation_pauses": True,
    "session_id": "trading-session-001",
})

lineage = client.get_decision_lineage("ask", {"question": "Should I buy NVDA?"})
print(lineage["decision"])     # "review" — high-stakes detected

trail = client.get_audit_trail(session_id="trading-session-001")
```

## Why VeroQ?

| | What you get |
|---|---|
| **Trust** | Evidence chains and confidence breakdowns on every response |
| **Safety** | Permission engine, decision lineage, human-in-the-loop escalation |
| **Cost control** | 3 cost modes, per-step budgets, credit transparency |
| **Continuous improvement** | Feedback loop with web search fallback fills data gaps over time |
| **Multi-domain** | Finance (flagship), legal, research, compliance, custom verticals |

## Cached Shield — High-Volume Pipelines

```python
from veroq import CachedShield

cached = CachedShield(max_cache=1000, ttl_seconds=3600)
result = cached("NVIDIA reported $22B in Q4 revenue")   # API call
result = cached("NVIDIA reported $22B in Q4 revenue")   # instant, 0 credits
print(cached.stats())  # {'hits': 1, 'misses': 1, 'hit_rate': 0.5, 'size': 1}
```

## Agent Monitoring

```python
# Set up autonomous monitoring
client.agent_auto_monitor("my-bot", trust_threshold=0.7, check_interval_hours=6)

# Manual health check
health = client.agent_health_check("my-bot")
print(health["health"]["status"])        # "healthy" or "degraded"
print(health["health"]["trust_trend"])   # "improving" / "declining" / "stable"
```

## All Methods

| Method | Description |
|--------|-------------|
| `shield(text)` | Verify any LLM output (module-level) |
| `CachedShield(...)` | Local LRU cache for high-volume shield calls |
| `ask(question)` | Ask any financial question |
| `ask_stream(question)` | Stream via SSE |
| `verify(claim)` | Fact-check with evidence chain |
| `verify_output(text)` | Extract + verify claims from any text |
| `create_verified_swarm(query, ...)` | Multi-agent verified pipeline |
| `create_runtime(query, ...)` | Domain-specific runtime |
| `call_external_tool(server_id, tool, params)` | Secure external tool proxy |
| `submit_feedback(...)` | Self-improvement feedback |
| `memory_store(agent_id, key, value)` | Store agent memory |
| `memory_recall(agent_id)` | Recall agent memories |
| `memory_list(agent_id)` | List all agent memories |
| `agent_auto_monitor(agent_id)` | Configure autonomous monitoring |
| `agent_health_check(agent_id)` | Trigger health check |
| `watch(tickers)` | Real-time SSE verification stream |
| `configure_enterprise(config)` | Enterprise governance |
| `get_decision_lineage(tool, input, output)` | Decision audit |
| `get_audit_trail(session_id?)` | Audit trail |
| `feed()` / `brief(id)` / `search(query)` | Intelligence briefs |
| `stream(categories?)` | Stream briefs via SSE |

## Error Handling

```python
from veroq import AuthenticationError, RateLimitError, NotFoundError

try:
    client.ask("NVDA analysis")
except RateLimitError as e:
    print(f"Retry after: {e.retry_after}s")
```

## Backward Compatibility

`PolarisClient` aliased to `VeroqClient`. Both `VEROQ_API_KEY` and `POLARIS_API_KEY` supported.

## Links

- [API Reference](https://veroq.ai/docs) | [MCP Server](https://www.npmjs.com/package/veroq-mcp) | [TypeScript SDK](https://www.npmjs.com/package/@veroq/sdk) | [Enterprise](https://veroq.ai/pricing)
