Metadata-Version: 2.4
Name: largestack
Version: 1.0.1
Summary: Largestack AI — production-grade candidate framework for typed agents, tools, RAG, guardrails, and orchestration
Author: RivaiLabs
Maintainer-email: RivaiLabs <hello@rivailabs.com>
License-Expression: Apache-2.0
Project-URL: PyPI, https://pypi.org/project/largestack/
Keywords: ai,agents,llm,framework,mcp,observability
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: httpx[http2]>=0.28.1
Requires-Dist: anyio>=4.13.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: tenacity>=9.0
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.0
Requires-Dist: fastapi>=0.128.2
Requires-Dist: uvicorn[standard]>=0.46.0
Requires-Dist: starlette<2.0.0,>=1.0.1
Requires-Dist: jinja2>=3.1
Requires-Dist: sse-starlette>=3.4.2
Requires-Dist: cryptography>=42.0
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: openpyxl>=3.1
Provides-Extra: openai
Requires-Dist: openai>=1.50; extra == "openai"
Requires-Dist: tiktoken>=0.7; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == "anthropic"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.25; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.25; extra == "otel"
Provides-Extra: guard
Requires-Dist: presidio-analyzer>=2.2; extra == "guard"
Requires-Dist: presidio-anonymizer>=2.2; extra == "guard"
Provides-Extra: rag
Requires-Dist: sentence-transformers>=3.0; extra == "rag"
Requires-Dist: beautifulsoup4>=4.12; extra == "rag"
Requires-Dist: faiss-cpu>=1.8; extra == "rag"
Requires-Dist: duckdb>=0.10; extra == "rag"
Requires-Dist: qdrant-client>=1.9; extra == "rag"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.24; extra == "test"
Requires-Dist: pytest-timeout>=2.3; extra == "test"
Requires-Dist: hypothesis>=6.0; extra == "test"
Requires-Dist: respx>=0.22; extra == "test"
Provides-Extra: postgres
Requires-Dist: psycopg[binary,pool]>=3.1; extra == "postgres"
Requires-Dist: sqlalchemy>=2.0; extra == "postgres"
Provides-Extra: migrations
Requires-Dist: alembic>=1.13; extra == "migrations"
Requires-Dist: sqlalchemy>=2.0; extra == "migrations"
Provides-Extra: all
Requires-Dist: largestack[anthropic,dev-server,guard,litellm,mcp,migrations,office,openai,otel,postgres,rag,test]; extra == "all"
Provides-Extra: dev
Requires-Dist: largestack[all]; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Provides-Extra: litellm
Requires-Dist: litellm>=1.83.14; extra == "litellm"
Provides-Extra: mcp
Requires-Dist: fastapi>=0.110; extra == "mcp"
Requires-Dist: uvicorn>=0.27; extra == "mcp"
Provides-Extra: dev-server
Requires-Dist: fastapi>=0.110; extra == "dev-server"
Requires-Dist: uvicorn[standard]>=0.27; extra == "dev-server"
Requires-Dist: watchfiles>=0.21; extra == "dev-server"
Provides-Extra: office
Requires-Dist: openpyxl>=3.1; extra == "office"
Requires-Dist: python-pptx>=0.6.23; extra == "office"
Requires-Dist: pandas>=2.2; extra == "office"
Dynamic: license-file

# Largestack AI

[![PyPI version](https://img.shields.io/pypi/v/largestack.svg)](https://pypi.org/project/largestack/)
[![Python](https://img.shields.io/pypi/pyversions/largestack.svg)](https://pypi.org/project/largestack/)
[![License](https://img.shields.io/pypi/l/largestack.svg)](https://pypi.org/project/largestack/)

**Largestack AI** is a Python 3.11+ production-grade candidate framework for typed agents, tools, RAG, guardrails, observability, and orchestration.

It is designed for developers who want to build real AI systems without starting from a blank file: support-ticket agents, RAG assistants, code reviewers, workflow automations, BFSI governance flows, and enterprise-style AI copilots.

> Current status: **v1.0 Release Candidate / controlled-pilot ready**. Ubuntu, Mac evidence, Windows clean validation, Docker, security, package, DeepSeek live validation, and 24-hour soak evidence have passed.

## Install

```bash
pip install largestack
```

Verify:

```bash
largestack --help
python -c "import largestack; print(largestack.__version__)"
```

---

## Why Largestack?

Most agent frameworks solve only one layer: agents, chains, RAG, or observability. Largestack brings the main production surfaces together:

| Layer | What Largestack provides |
|---|---|
| Agents | `Agent`, typed agents, role-based agents, multi-agent teams |
| Tools | Safe tool calling, schemas, retries, timeout controls, approval policies |
| Workflows | Sequential, parallel, router, supervisor, graph/DAG-style orchestration |
| RAG | Loaders, chunking, retrievers, rerankers, vector stores, citations, no-answer behavior |
| Guardrails | PII checks, injection controls, topic/sensitive data policies, tool/provider policies |
| Memory | Buffer, long-term, vector-backed, shared and isolated memory patterns |
| Observability | Traces, cost tracking, event logs, dashboard APIs, OTEL helpers |
| Enterprise | RBAC, audit trail, tenant scoping, SSO/session modules, payment/billing scaffolds |
| Deployment | Docker, Compose, Helm charts, CI validation, release evidence |
| Testing | Unit, integration, security, RAG eval, live provider validation, generated project checks |

---

## Development quickstart

### 1. Open a source checkout

```bash
# Public GitHub clone URL should be added after repository visibility is enabled.
cd largestack
```

### 2. Create environment

```bash
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip setuptools wheel
```

### 3. Install editable development dependencies

For normal source development:

```bash
python -m pip install -e ".[dev]"
```

For CPU-only PyTorch dependency resolution on Linux/macOS:

```bash
PIP_EXTRA_INDEX_URL=https://download.pytorch.org/whl/cpu \
python -m pip install -e ".[dev]"
```

### 4. Run a first validation

```bash
python -m pytest tests/unit/test_memory.py -q --tb=short
```

### 5. Run the full suite

```bash
python -m pytest tests -q --tb=short -ra
```

---

## Minimal agent example

```python
import asyncio
from largestack import Agent

async def main():
    agent = Agent(
        name="assistant",
        llm="deepseek/deepseek-chat",
        instructions="Be concise and practical."
    )
    result = await agent.run("Explain Largestack in one sentence.")
    print(result.content)

asyncio.run(main())
```

For deterministic tests, use the built-in test/offline model patterns instead of a live cloud provider.

---

## Live provider setup

DeepSeek:

```bash
export LARGESTACK_DEEPSEEK_API_KEY="your_key_here"
python examples/01_hello/main.py
```

OpenAI:

```bash
export LARGESTACK_OPENAI_API_KEY="your_key_here"
export LARGESTACK_DEFAULT_MODEL="openai/gpt-4o-mini"
python examples/01_hello/main.py
```

Never commit `.env` or paste API keys into source files.

---

## LLM/API provider support

Largestack is provider-switchable. The core agent, workflow, RAG, guardrail,
and observability layers run through a model string such as
`openai/gpt-4o-mini`, `anthropic/claude-sonnet-4-6`,
`deepseek/deepseek-chat`, `litellm/groq/llama-3.1-70b-versatile`, or
`local/llama3.2`.

Recommended public claim:

> Largestack supports OpenAI/GPT, Anthropic/Claude, DeepSeek, LiteLLM,
> Ollama/local models, and many OpenAI-compatible providers through a
> verified/partial capability matrix.

Do not claim every provider has identical production-grade tool calling,
structured output, streaming, and cost tracking until that provider/model has
passed live E2E validation.

| Provider/API path | Model string example | Env/config | Status |
|---|---|---|---|
| OpenAI / GPT | `openai/gpt-4o-mini` | `LARGESTACK_OPENAI_API_KEY` | Verified primary adapter path |
| Anthropic / Claude | `anthropic/claude-sonnet-4-6` | `LARGESTACK_ANTHROPIC_API_KEY` | Verified native adapter path |
| DeepSeek | `deepseek/deepseek-chat` | `LARGESTACK_DEEPSEEK_API_KEY` | Live E2E validated |
| LiteLLM gateway | `litellm/<provider>/<model>` | Provider-specific LiteLLM env vars | Partial; downstream capability varies |
| Local OpenAI-compatible | `local/<model>` | `LARGESTACK_OPENAI_COMPATIBLE_BASE_URL` | Partial; gateway/model capability varies |
| Ollama native | `ollama/<model>` | `LARGESTACK_OLLAMA_BASE_URL` optional | Partial; chat path first |
| Azure OpenAI | `azure/<deployment>` | `LARGESTACK_AZURE_OPENAI_KEY`, `LARGESTACK_AZURE_OPENAI_ENDPOINT` | Partial; deployment-specific |
| Groq, Mistral, OpenRouter, xAI, Cerebras, SambaNova, NVIDIA | `<provider>/<model>` | `LARGESTACK_<PROVIDER>_API_KEY` | Partial/OpenAI-compatible; verify live |
| Google/Gemini, Cohere, Bedrock | `<provider>/<model>` | Provider env/credentials | Partial; feature support differs |

Inspect the runtime matrix:

```bash
python - <<'PY'
from largestack import provider_support_matrix
for row in provider_support_matrix():
    print(row["provider"], row["status"], "tools=", row["tool_calling"], "structured=", row["structured_output"])
PY
```

Run the provider-switchable flow demo offline:

```bash
python examples/provider_flow_demo/main.py
```

Run the same flow against GPT:

```bash
export LARGESTACK_OPENAI_API_KEY="your_key_here"
export LARGESTACK_DEFAULT_MODEL="openai/gpt-4o-mini"
export LARGESTACK_FLOW_DEMO_LIVE=1
python examples/provider_flow_demo/main.py
```

Run the same flow against Claude:

```bash
export LARGESTACK_ANTHROPIC_API_KEY="your_key_here"
export LARGESTACK_DEFAULT_MODEL="anthropic/claude-sonnet-4-6"
export LARGESTACK_FLOW_DEMO_LIVE=1
python examples/provider_flow_demo/main.py
```

Run the same flow against a local OpenAI-compatible endpoint:

```bash
export LARGESTACK_OPENAI_COMPATIBLE_BASE_URL="http://localhost:11434/v1"
export LARGESTACK_OPENAI_COMPATIBLE_API_KEY="ollama"
export LARGESTACK_DEFAULT_MODEL="local/llama3.2"
export LARGESTACK_FLOW_DEMO_LIVE=1
python examples/provider_flow_demo/main.py
```

---

## Flow demo

The quickest workflow demo is `examples/provider_flow_demo/main.py`. It runs
offline by default and can be switched to any configured provider by changing
only `LARGESTACK_DEFAULT_MODEL`.

```mermaid
flowchart LR
    U[User task] --> I[Intake agent]
    I --> P[Planner agent]
    P --> R[Responder agent]
    R --> O[Final answer]
```

What the demo proves:

- one task flows through three agents,
- DAG dependencies control execution order,
- each agent can use the same model string or provider family,
- offline `TestModel` validation requires no API key,
- live mode works with GPT, Claude, DeepSeek, LiteLLM, or local-compatible
  providers when credentials are configured.

---

## Built-in example areas

| Example | Purpose |
|---|---|
| `examples/00_offline_test_model.py` | Offline deterministic model check |
| `examples/01_hello` | Basic provider-backed agent |
| `examples/02_tools` | Tool calling |
| `examples/03_team` | Multi-agent/team behavior |
| `examples/04_guards` | Guardrails/security behavior |
| `examples/05_rag_knowledge` | RAG with knowledge files |
| `examples/06_streaming` | Streaming responses |
| `examples/07_structured` | Structured outputs |
| `examples/08_mcp_server` | MCP server pattern |
| `examples/10_full_app` | Integrated app pattern |
| `examples/provider_flow_demo` | Provider-switchable workflow demo |
| `examples/rag_basic` | Basic RAG assistant |
| `examples/fintech_kyc` | BFSI/KYC style workflow |
| `examples/riva_ai` | Riva/Largestack demo pipelines |

---

## Validation status

Latest confirmed release-candidate evidence includes:

| Gate | Status |
|---|---|
| Ubuntu full pytest | Passed |
| Mac validation | Passed / evidence added |
| Windows validation | Passed / clean Windows validation confirmed |
| DeepSeek live difficult projects | 5/5 passed |
| Full DeepSeek integration suite | Passed with one known provider-format skip |
| Provider support matrix | Present / explicit verified-partial-adapter statuses |
| Offline provider flow demo | Passed with `TestModel` |
| Security suite | Passed |
| RAG eval suite | Passed |
| Package build + twine check | Passed |
| Docker runtime `/health` | Passed |
| Helm lint/template | Passed |
| 4-hour soak evidence | Passed |
| 24-hour soak | Passed / 210 successful cycles / 0 recorded failures |

---

## Architecture at a glance

```mermaid
flowchart TD
    U[User / API / CLI / App] --> C[CLI or SDK]
    C --> A[Agent Runtime]
    A --> W[Workflow Orchestrator]
    A --> T[Tool Registry]
    A --> M[Memory Layer]
    A --> R[RAG Layer]
    A --> G[Guardrails]
    W --> S[State / Checkpoints]
    T --> I[Integrations]
    R --> V[Vector Stores / Retrievers / Rerankers]
    G --> E[Enterprise Policies]
    A --> O[Observability]
    O --> D[Dashboard / Metrics / Traces]
    E --> AUD[Audit / RBAC / Tenant Controls]
    C --> DEP[Docker / Compose / Helm]
```

---

## Repository map

| Path | Purpose |
|---|---|
| `largestack/_core` | Main agent/tool/runtime primitives |
| `largestack/_workflow` | Workflow graph, checkpoints, interrupts, subgraphs |
| `largestack/_rag` | RAG query engines, eval, summary index |
| `largestack/_memory` | Memory stores and memory tools |
| `largestack/_guard` | Provider/tool guardrail policies |
| `largestack/_security` | Sandbox, permissions, vault, encryption, network controls |
| `largestack/_enterprise` | RBAC, audit, tenant, SSO/session, billing/payment modules |
| `largestack/_observe` | Cost, traces, OTEL, telemetry helpers |
| `largestack/_dashboard` | Dashboard app and APIs |
| `largestack/_integrations` | Provider/tool integrations |
| `largestack/_templates` | Project starter templates |
| `examples/` | Runnable examples |
| `tests/` | Unit, integration, security, RAG eval tests |
| `scripts/` | Certification, smoke, scenario, and live DeepSeek validation scripts |
| `deploy/` | Docker, Compose, Helm, monitoring assets |
| `release_evidence/` | Validation evidence and release proof |

---

## Production-positioning honesty

Largestack is strong for:

- developer demos,
- investor demos,
- internal AI platform experiments,
- controlled pilots,
- agentic framework portfolio proof,
- private beta deployments.

Largestack should not yet be marketed as:

- fully BFSI-certified,
- SOC2/ISO-certified,
- full LangChain/LangGraph ecosystem replacement,
- public SaaS production platform without load tests, external VAPT, and real Kubernetes install proof.

Known limitations are tracked in [`docs/known-limitations.md`](docs/known-limitations.md). Review that file before publishing release, SaaS, BFSI, or regulated-enterprise claims.

---

## Roadmap

| Priority | Work |
|---|---|
| P0 | Add load/concurrency evidence after completed 24h soak |
| P0 | Queue/backpressure for high traffic |
| P0 | Distributed workers and job leasing |
| P0 | Durable replay/checkpoint recovery |
| P1 | Real Kubernetes cluster install test |
| P1 | Observability UI polish and replay debugger |
| P1 | More beginner templates and tutorials |
| P2 | Public docs website |
| P2 | Community examples and plugin ecosystem |
| P3 | Enterprise certifications, VAPT, compliance evidence |

---

## License

Apache-2.0.
