Metadata-Version: 2.4
Name: metacog
Version: 1.0.0
Summary: Metacog Python SDK — Governed vertical AI for regulated industries
Home-page: https://github.com/metacog-ai/metacog-python
Author: Metacog
Author-email: api@metacog.ai
Project-URL: Documentation, https://docs.metacog.ai
Project-URL: API Reference, https://docs.metacog.ai/api
Project-URL: Source, https://github.com/metacog-ai/metacog-python
Project-URL: Bug Tracker, https://github.com/metacog-ai/metacog-python/issues
Keywords: ai compliance india payroll gst tds governance hallucination
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: python-dotenv; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Metacog Python SDK

The world's first governed vertical AI SDK for regulated industries in India.

[![PyPI version](https://badge.fury.io/py/metacog.svg)](https://pypi.org/project/metacog/)
[![Governance Score](https://img.shields.io/badge/governance-60%25-green)](https://metacog.ai/governance)
[![Hallucination Rate](https://img.shields.io/badge/hallucination-0%25-brightgreen)](https://metacog.ai/eval)

## What makes Metacog different

Every other AI API gives you an answer. Metacog gives you a **governed** answer.

Every response includes:
- **Confidence score** — how certain is the AI? (M1)
- **Source citations** — which act and section? (V3)
- **PII protection** — no PAN, Aadhaar, or salary data leaked (M7)
- **Hallucination risk** — low / medium / high (M6)
- **Drift status** — are answers consistent over time? (M3)

**Measured results:**
- 0% hallucination rate across 37 Indian compliance questions
- 60% governance score vs 7% industry average
- +53 percentage points advantage over nearest competitor

## Installation

```bash
pip install metacog
```

## Quick start

```python
import metacog

client = metacog.Metacog(api_key="mk-...")

response = client.governed.create(
    model=metacog.METACOG_M3,
    prompt="What is the TDS rate for salary of 12 lakhs under new regime?",
)

print(response.answer)
# TDS for ₹12 lakh salary under new tax regime for FY 2024-25...

print(response.confidence)
# 0.94

print(response.sources)
# ['Income Tax Act Section 192', 'Finance Act 2024']

print(response.governance_passed)
# True

print(response.hallucination_risk)
# 'low'
```

## Governance parameters

```python
response = client.governed.create(
    model=metacog.METACOG_M3,
    prompt="What is the PF contribution rate?",
    governance=metacog.GovernanceConfig(
        vertical="payroll",
        confidence_threshold=0.85,   # Block if confidence < 85%
        pii_scan=True,               # Scan for PAN, Aadhaar, salary
        cite_sources=True,           # Require act/section citations
        drift_check=True,            # Check for answer drift
    )
)

# Check if response is fully safe
if response.is_safe:
    print(response.answer)
else:
    print(f"Escalation required: confidence={response.confidence}")
```

## Async usage

```python
import asyncio
import metacog

async def check_compliance():
    client = metacog.Metacog(api_key="mk-...")
    response = await client.governed.acreate(
        model=metacog.METACOG_M3,
        prompt="GSTR-3B due date for May 2026?",
        governance=metacog.GovernanceConfig(vertical="gst")
    )
    return response

response = asyncio.run(check_compliance())
print(response.answer)
```

## Available models

| Model | Use case | Speed | Governance |
|-------|----------|-------|-----------|
| `metacog-m1` | High-volume queries, simple lookups | Fast | Standard |
| `metacog-m3` | Daily compliance work (recommended) | Balanced | Enhanced |
| `metacog-m7` | Complex reasoning, filing decisions | Thorough | Maximum |
| `metacog-f1` | Finance & payroll specialist | Fast | Standard |
| `metacog-b1` | Banking & RBI compliance | Balanced | Enhanced |
| `metacog-h1` | Healthcare compliance | Balanced | Enhanced |

## Verticals supported

- `payroll` — TDS, PF, ESI, Form 16, Professional Tax
- `gst` — GSTR-1/3B/9, ITC, E-invoice, RCM
- `labour_law` — Factories Act, Maternity, Minimum Wages, Gratuity, Bonus
- `banking` — RBI, KYC/AML, Basel III, NPA, CRR/SLR
- `healthcare` — ABDM, Clinical Act, Drug Act, DPDP
- `insurance` — IRDAI, Claims, Motor, Life, Health

## Environment variables

```bash
export METACOG_API_KEY="mk-..."
export METACOG_BASE_URL="https://api.metacog.ai"  # optional
```

## Get an API key

Visit [metacog.ai](https://metacog.ai) or email [api@metacog.ai](mailto:api@metacog.ai)

Free tier: 1,000 API calls/month. No credit card required.

## Licensing

For embedding Metacog in your product (ERP, HRMS, fintech), contact [licensing@metacog.ai](mailto:licensing@metacog.ai)

Revenue share program available for CA firms and software partners.

## Links

- [Documentation](https://docs.metacog.ai)
- [API Reference](https://docs.metacog.ai/api)
- [Governance Score](https://metacog.ai/governance)
- [Hallucination Rate Report](https://metacog.ai/eval)
- [Pricing](https://metacog.ai/pricing)

---

*Metacog — Governed Intelligence. Made in India. Built for the world.*
