Metadata-Version: 2.4
Name: snowflake-cortex-agents
Version: 0.1.0
Summary: Python SDK for Snowflake Cortex Agents and Analyst
Keywords: snowflake,cortex,agents,analyst,ai,llm,rest
Author: Chuliang Xiao
Author-email: Chuliang Xiao <ChuliangX@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: httpx>=0.27.0
Requires-Dist: snowflake-cortex-agents[dotenv,charts,dev,docs] ; extra == 'all'
Requires-Dist: altair>=5.0.0 ; extra == 'charts'
Requires-Dist: pandas>=1.0.0 ; extra == 'charts'
Requires-Dist: pre-commit>=4.0.0 ; extra == 'dev'
Requires-Dist: pytest>=7.0.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0 ; extra == 'dev'
Requires-Dist: ruff>=0.7.0 ; extra == 'dev'
Requires-Dist: ty>=0.0.26 ; extra == 'dev'
Requires-Dist: mkdocs>=1.5.0,<2.0 ; extra == 'docs'
Requires-Dist: mkdocs-material>=9.0.0 ; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24.0 ; extra == 'docs'
Requires-Dist: python-dotenv>=1.0.0 ; extra == 'dotenv'
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/ChuliangXiao/snowflake-cortex-agents
Project-URL: Documentation, https://github.com/ChuliangXiao/snowflake-cortex-agents/blob/main/README.md
Project-URL: Repository, https://github.com/ChuliangXiao/snowflake-cortex-agents
Project-URL: Issues, https://github.com/ChuliangXiao/snowflake-cortex-agents/issues
Provides-Extra: all
Provides-Extra: charts
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: dotenv
Description-Content-Type: text/markdown

﻿# Snowflake Cortex Agents Python SDK

Python SDK for Snowflake Cortex Agents and Cortex Analyst, with sync and async clients, SSE streaming, and chart helpers for agent responses.

## Installation

Install from PyPI:

```bash
pip install snowflake-cortex-agents
```

Optional extras:

- `dotenv` for `.env` loading
- `charts` for Altair and Pandas chart rendering
- `all` for all optional dependencies

```bash
pip install snowflake-cortex-agents[all]
```

For source and contributor setup, see [CONTRIBUTING.md](CONTRIBUTING.md).

## Credentials

Set credentials with environment variables:

```bash
export SNOWFLAKE_ACCOUNT_URL=https://your-account.snowflakecomputing.com
export SNOWFLAKE_PAT=your-personal-access-token
```

Or install `snowflake-cortex-agents[dotenv]` and use a `.env` file:

```env
SNOWFLAKE_ACCOUNT_URL=https://your-account.snowflakecomputing.com
SNOWFLAKE_PAT=your-personal-access-token
```

When working from this repository, you can copy [.env.example](.env.example) to `.env` and fill in your values.

## Quick Start

Both Cortex Agent `run()` and Cortex Analyst `message()` return streaming SSE responses.

### Run an existing agent

```python
from cortex_agents import CortexAgent

with CortexAgent() as client:
    response = client.run(
        "What's this month revenue?",
        agent_name="MY_AGENT",
        database="MY_DATABASE",
        schema="MY_SCHEMA",
    )

    for event in response:
        if event["type"] == "text.delta":
            print(event["data"]["text"], end="", flush=True)
```

### Ask Cortex Analyst a question

```python
from cortex_agents import CortexAnalyst

with CortexAnalyst() as analyst:
    response = analyst.message(
        question="What were the top 5 products by revenue last month?",
        semantic_model_file="@my_stage/semantic_model.yaml",
    )

    for event in response:
        if event["type"] == "text.delta":
            print(event["data"]["text"], end="", flush=True)
        elif event["type"] == "sql.delta":
            print(event["data"]["sql"], end="", flush=True)
```

### Async support

Async clients are available via `AsyncCortexAgent` and `AsyncCortexAnalyst`. See [docs/quickstart.md](docs/quickstart.md) and [examples/example_agent_async.py](examples/example_agent_async.py) for runnable async examples.

## Documentation

- [docs/installation.md](docs/installation.md): installation, optional extras, and credential setup
- [docs/quickstart.md](docs/quickstart.md): sync and async getting-started flows
- [docs/guides/agents.md](docs/guides/agents.md): Cortex Agent usage
- [docs/guides/analyst.md](docs/guides/analyst.md): Cortex Analyst usage
- [docs/guides/threads_api.md](docs/guides/threads_api.md): thread management
- [docs/guides/agents_threads.md](docs/guides/agents_threads.md): conversational agent patterns
- [USAGE.md](USAGE.md): broader API usage notes
- [docs/guides/chart_plotting.md](docs/guides/chart_plotting.md): chart rendering helpers
- [examples/](examples/): runnable examples

## Requirements

- Python 3.10+
- Snowflake account with Cortex enabled
- Personal Access Token (PAT)

## Contributing

Development workflow, uv-based setup, and quality checks are documented in [CONTRIBUTING.md](CONTRIBUTING.md).

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE).
