Metadata-Version: 2.4
Name: largestack
Version: 1.0.0
Summary: Largestack AI — production-grade candidate framework for typed agents, tools, RAG, guardrails, and orchestration
Author-email: RivaiLabs <hello@rivailabs.com>
License-Expression: Apache-2.0
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

**Largestack AI** is an agentic AI framework for building practical AI applications with agents, tools, workflows, RAG, guardrails, observability, and deployment support in one project.

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.

---

## 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 |

---

## 5-minute quickstart

### 1. Get the source

```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

For normal 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.
