Metadata-Version: 2.4
Name: agenticstack
Version: 0.2.0
Summary: The WordPress of AI Agents - A modular, lightweight agentic framework
Project-URL: Homepage, https://agenticstack.dev
Project-URL: Documentation, https://docs.agenticstack.dev
Project-URL: Repository, https://github.com/AiConglomerate/AgenticStack
Author: AgenticStack Team
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agents,ai,framework,llm,modular
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Provides-Extra: all
Requires-Dist: anthropic>=0.18.0; extra == 'all'
Requires-Dist: boto3>=1.34.0; extra == 'all'
Requires-Dist: cohere>=5.0.0; extra == 'all'
Requires-Dist: google-generativeai>=0.3.0; extra == 'all'
Requires-Dist: groq>=0.4.0; extra == 'all'
Requires-Dist: mistralai>=0.1.0; extra == 'all'
Requires-Dist: ollama>=0.1.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: redis>=5.0.0; extra == 'all'
Requires-Dist: tiktoken>=0.5.0; extra == 'all'
Requires-Dist: together>=1.0.0; extra == 'all'
Provides-Extra: all-providers
Requires-Dist: anthropic>=0.18.0; extra == 'all-providers'
Requires-Dist: boto3>=1.34.0; extra == 'all-providers'
Requires-Dist: cohere>=5.0.0; extra == 'all-providers'
Requires-Dist: google-generativeai>=0.3.0; extra == 'all-providers'
Requires-Dist: groq>=0.4.0; extra == 'all-providers'
Requires-Dist: mistralai>=0.1.0; extra == 'all-providers'
Requires-Dist: ollama>=0.1.0; extra == 'all-providers'
Requires-Dist: openai>=1.0.0; extra == 'all-providers'
Requires-Dist: tiktoken>=0.5.0; extra == 'all-providers'
Requires-Dist: together>=1.0.0; extra == 'all-providers'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18.0; extra == 'anthropic'
Provides-Extra: bedrock
Requires-Dist: boto3>=1.34.0; extra == 'bedrock'
Provides-Extra: cloud-providers
Requires-Dist: anthropic>=0.18.0; extra == 'cloud-providers'
Requires-Dist: cohere>=5.0.0; extra == 'cloud-providers'
Requires-Dist: google-generativeai>=0.3.0; extra == 'cloud-providers'
Requires-Dist: groq>=0.4.0; extra == 'cloud-providers'
Requires-Dist: mistralai>=0.1.0; extra == 'cloud-providers'
Requires-Dist: openai>=1.0.0; extra == 'cloud-providers'
Requires-Dist: tiktoken>=0.5.0; extra == 'cloud-providers'
Requires-Dist: together>=1.0.0; extra == 'cloud-providers'
Provides-Extra: cohere
Requires-Dist: cohere>=5.0.0; extra == 'cohere'
Provides-Extra: commerce
Requires-Dist: cryptography>=42.0.0; extra == 'commerce'
Provides-Extra: dev
Requires-Dist: cryptography>=42.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: agenticstack-cache>=0.1.0; extra == 'full'
Requires-Dist: agenticstack-costs>=0.1.0; extra == 'full'
Requires-Dist: agenticstack-dashboard>=0.1.0; extra == 'full'
Requires-Dist: agenticstack-guard-secrets>=0.1.0; extra == 'full'
Requires-Dist: agenticstack-hitl>=0.1.0; extra == 'full'
Requires-Dist: agenticstack-loaders>=0.1.0; extra == 'full'
Requires-Dist: agenticstack-memory-sqlite>=0.1.0; extra == 'full'
Requires-Dist: agenticstack-tools-data>=0.1.0; extra == 'full'
Requires-Dist: agenticstack-tools-essentials>=0.1.0; extra == 'full'
Requires-Dist: agenticstack-tools-web>=0.1.0; extra == 'full'
Requires-Dist: agenticstack-transcripts>=0.1.0; extra == 'full'
Requires-Dist: agenticstack-vectorstore-chroma>=0.1.0; extra == 'full'
Requires-Dist: agenticstack-vectorstore-pgvector>=0.1.0; extra == 'full'
Requires-Dist: agenticstack-vectorstore-qdrant>=0.1.0; extra == 'full'
Provides-Extra: google
Requires-Dist: google-generativeai>=0.3.0; extra == 'google'
Provides-Extra: groq
Requires-Dist: groq>=0.4.0; extra == 'groq'
Provides-Extra: local-providers
Requires-Dist: ollama>=0.1.0; extra == 'local-providers'
Provides-Extra: mistral
Requires-Dist: mistralai>=0.1.0; extra == 'mistral'
Provides-Extra: ollama
Requires-Dist: ollama>=0.1.0; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Requires-Dist: tiktoken>=0.5.0; extra == 'openai'
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == 'redis'
Provides-Extra: together
Requires-Dist: together>=1.0.0; extra == 'together'
Description-Content-Type: text/markdown

# AgenticStack

**Agents you install, not build.**

AgenticStack is an open, Apache-2.0 agent runtime with **typed capability
contracts**, **permissioned plugins**, and a **marketplace** where working
agents are one command away.

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
[![PyPI](https://badge.fury.io/py/agenticstack.svg)](https://pypi.org/project/agenticstack/)

```bash
pip install agenticstack
stack agent install docs-qa     # shows permissions, verifies sha256
stack run docs-qa               # prompts live in ./agents/docs-qa — edit freely
```

That's the whole pitch: a working agent in two commands, unpacked as an
**editable bundle** — open its prompt files, drop documents into its
`knowledge/` folder, make it yours. The WordPress model, for agents.

---

## Why AgenticStack (the honest version)

Plenty of good frameworks orchestrate agents. AgenticStack is different in
five specific, checkable ways:

**1. Typed capability contracts with shipped conformance suites.**
Memory, vector stores, providers, retrieval, and guards are typed contracts
(`agenticstack.api`), each with a pytest conformance suite the framework
itself passes in CI. A plugin author subclasses one fixture; **a green suite
is a proof of compatibility, not a promise**. No other open framework ships
this.

```python
# tests/test_conformance.py — this is a plugin's entire proof
import pytest
from agenticstack.testing import MemoryContract
from my_plugin import MyMemory

class TestMyMemoryConformance(MemoryContract):
    @pytest.fixture
    def memory(self):
        return MyMemory()
```

**2. Permissions before anything runs.**
Every plugin and agent declares `network` / `filesystem` / `shell` / `env`
in its `agentstack.toml` manifest. You see the request at install; the
runtime **refuses to load** anything you haven't granted — enforced *before
a single line of plugin code executes*. (Loaded code runs with process
privileges — this is a guardrail and an audit surface, not a sandbox. We
say so plainly; see [SECURITY.md](SECURITY.md).)

**3. Packaged agents as products.**
Agents ship as `.stack` bundles: prompts, optional skills, eval fixtures,
a knowledge folder — versioned, sha256-verified, installed into your
project where you can read and edit everything. Publishing one requires
≥5 passing eval fixtures (`stack agent eval`).

**4. Tools that defend themselves.**
Our HTTP tool blocks SSRF by checking *resolved* addresses (including
IPv4-mapped IPv6, cloud-metadata endpoints, and every redirect hop). Our
SQL tool is read-only at the engine level via SQLite's authorizer
callback — not a substring blacklist. Our filesystem tools resolve
symlinks before deciding a path is inside the sandbox. Each control is
tested adversarially, and the residual gaps (DNS rebinding, TOCTOU) are
documented rather than hidden.

**5. A neutral marketplace.**
The [registry](registry-seed/) is a static, CDN-served index over PyPI and
publisher releases — open metadata, yank kill-switch, security advisories
(`stack plugin audit`), verified publishers. No cloud gravity: the core
never phones home, and there is no hosted tier the framework nudges you
into.

## Quickstart in code

```python
from agenticstack import Agent, skill

@skill(id="greet", description="Greet the user")
async def greet(name: str) -> str:
    return f"Hello, {name}!"

agent = Agent(
    name="Greeter",
    skills=[greet],
    model="gpt-4o-mini",        # provider inferred; 12 providers supported
    memory="sqlite",            # capability name -> resolved from installed plugins
    guards=["pii", "secrets"],  # same for guards
)
print(agent.run("Say hi to Ada"))
```

Capabilities resolve by name through the plugin registry — swap `sqlite`
for any installed memory backend without touching agent code. Providers
get retry/backoff/timeouts; the tool loop chains multi-step tool calls;
`agent.stream()` streams. Also built in:

```python
from pydantic import BaseModel
from agenticstack import FallbackProvider

class Invoice(BaseModel):
    total: float
    currency: str

invoice = await agent.chat_structured("Bill: 3 units at $12", model=Invoice)
agent = Agent(name="Resilient", provider=FallbackProvider(["openai", "anthropic"]))
```


## The catalog — every package is ours

No wrappers around other frameworks. Each plugin is first-party code
implementing a typed contract, with its own conformance or adversarial
tests and a declared permission set.

| Package | Kind | What it does |
| --- | --- | --- |
| `agenticstack-vectorstore-chroma` | plugin | ChromaDB vector store (persistent or in-memory) |
| `agenticstack-vectorstore-qdrant` | plugin | Qdrant — in-memory, local, or remote; passes the full contract against the real client |
| `agenticstack-vectorstore-pgvector` | plugin | PostgreSQL/pgvector — hand-written SQL, injection-hardened identifiers |
| `agenticstack-memory-sqlite` | plugin | SQLite long-term memory with FTS5 search, zero deps |
| `agenticstack-loaders` | plugin | PDF (per-page), DOCX (sections + tables), HTML, web fetch, same-origin crawl |
| `agenticstack-tools-web` | plugin | HTTP client with real SSRF defense, pluggable web search, page-to-text |
| `agenticstack-tools-data` | plugin | Read-only SQL (engine authorizer), sandboxed filesystem, CSV querying |
| `agenticstack-tools-essentials` | plugin | Safe skills pack: calculator, dates, text utilities |
| `agenticstack-guard-secrets` | plugin | Redacts API keys/tokens/credentials from agent traffic |
| `agenticstack-hitl` | plugin | Approvals, review queues, feedback collection, intervention points |
| `agenticstack-dashboard` | plugin | Live local dashboard of plugins, hooks, and agent activity |
| `agenticstack-costs` | plugin | Per-agent token/cost tracking with budget warnings |
| `agenticstack-transcripts` | plugin | JSONL audit transcripts of every run, tool call, and error |
| `agenticstack-cache` | plugin | LLM response caching (in-memory LRU or SQLite) as a provider wrapper |
| `docs-qa` | agent | Answers strictly from your documents, with citations |
| `code-reviewer` | agent | Severity-ranked code review with checklist skills |
| `support-bot` | agent | Ticket triage with escalation rules |
| `invoice-bot` | agent | Invoicing and margin math that shows its work |
| `standup-scribe` | agent | Turns raw notes into standup summaries (prompt-only bundle) |

```bash
pip install "agenticstack[full]"   # the whole catalog
```

Browse them in the [marketplace](marketplace/index.html) — a static site
over the same `index.json` the CLI reads.

## Agent architectures

Four executing reasoning patterns, not scaffolding — each emits the
standard hooks, so cost tracking and transcripts work unchanged:

```python
from agenticstack import ReActAgent, PlanExecuteAgent, ReflectionAgent, SubAgentDelegator

result = await ReActAgent(agent).run("Research X and summarize")
result.trace          # (thought, action, observation) per step
result.usage          # tokens/cost for the whole run
```

| Pattern | What it does |
| --- | --- |
| `ReActAgent` | Thought → Action → Observation with an inspectable trace and graceful step-limit fallback |
| `PlanExecuteAgent` | Plans, then executes dependency-ordered steps with replanning on failure |
| `ReflectionAgent` | Draft → critique → revise until a score threshold or iteration cap |
| `SubAgentDelegator` | Supervisor delegating to named specialists, concurrently, with a depth cap |

## Build a plugin in 15 minutes

```bash
stack plugin create mymemory --capability memory
cd agenticstack-memory-mymemory && pip install -e ".[dev]"
stack plugin validate     # manifest lint + conformance suite + import-time check
stack plugin publish      # PyPI + registry PR
```

The failing conformance tests *are* the spec — implement until green.
Full tutorial: [docs/plugins/write-a-memory-plugin.md](docs/plugins/write-a-memory-plugin.md)
· manifest reference: [docs/reference/agentstack-toml.md](docs/reference/agentstack-toml.md)

## Build an agent bundle

```bash
stack agent create my-bot --template docs-qa
# edit prompts/system.md, drop files into knowledge/
stack agent eval my-bot      # fixture-based checks, pass/fail table + cost
stack agent pack my-bot      # -> my-bot-0.1.0.stack + sha256
```

## Architecture (one paragraph)

A thin core — kernel (events/config/lifecycle), `agenticstack.api`
(the contract surface, versioned as `API_VERSION`), and one plugin runtime
(`agentstack.toml` manifests, `DISCOVERED → RESOLVED → LOADED → ACTIVE`
with dependency/version/permission gating at RESOLVED) — beneath
first-party capability packages and agent bundles. Agents are wired
through public hook points (`agent.before_run`, `before_llm_call`,
`before_tool_call`, …), and the built-in memory, RAG, guard, and tracing
integrations attach through **the same hooks and registries a marketplace
plugin uses**. Also in the box: graph-based `StateGraph` workflows,
12 LLM providers, and offline license validation for paid plugins
(`agenticstack[commerce]`). Human oversight — approvals, review queues,
feedback, intervention points — is now an opt-in first-party plugin
(`pip install agenticstack-hitl`), included in `agenticstack[full]`.

## Status

**v0.2 (alpha).** APIs may change until the contracts freeze (then changes
go through the [contract-RFC process](GOVERNANCE.md)). The test suite —
including per-capability conformance suites the built-ins must pass — runs
in CI on Python 3.11–3.13. Migrating from v0.1: [MIGRATION.md](MIGRATION.md).

## Contributing

- [CONTRIBUTING.md](CONTRIBUTING.md) — DCO sign-off, dev setup, plugin-vs-core guide
- [GOVERNANCE.md](GOVERNANCE.md) — BDFL + contract RFCs (14-day window)
- [SECURITY.md](SECURITY.md) — private reporting, 72h acknowledgement
- The fastest way to contribute: **publish a plugin.** The registry's
  90-day goal is one external plugin passing a conformance suite.

## License

[Apache-2.0](LICENSE). The AgenticStack name and logo are trademarks; see
[NOTICE](NOTICE).
