Metadata-Version: 2.4
Name: maldaagenticore
Version: 0.5.0
Summary: Production-grade Python library for building scalable agentic AI systems
License: Apache-2.0
Requires-Python: >=3.11
Provides-Extra: all
Requires-Dist: anthropic>=0.25; extra == 'all'
Requires-Dist: asyncpg>=0.29; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: qdrant-client>=1.9; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29; extra == 'postgres'
Provides-Extra: qdrant
Requires-Dist: openai>=1.0; extra == 'qdrant'
Requires-Dist: qdrant-client>=1.9; extra == 'qdrant'
Provides-Extra: rich
Requires-Dist: rich>=13.0; extra == 'rich'
Description-Content-Type: text/markdown

# AgentiCore — Python Agentic Library

> **Version:** Pre-Alpha Design Document  
> **Date:** April 14, 2026  
> **Status:** Design Phase — not yet implemented  
> **Part of:** Multi-language AgentLibrary suite (Python → Rust → C++ → JavaScript)

---

## What Is AgentiCore?

**AgentiCore** is a production-grade, open-source Python library for building scalable agentic AI systems. It provides:

- A **composable core framework** — build any agent type without being forced into a specific pattern
- **Built-in reasoning strategies** — ReAct, Plan-Execute, Reflection, Tree-of-Thought, and custom
- **Tiered memory system** — working, episodic, semantic (RAG), and procedural memory
- **Type-safe tool system** — define, validate, and compose tools with full schema enforcement
- **Multi-agent orchestration** — supervisor, pipeline, fan-out, debate, swarm patterns
- **Built-in Web UI** — visual agent builder, tool creator, real-time run viewer, trace inspector
- **Plugin ecosystem** — extend anything without forking the library
- **First-class observability** — structured tracing, cost tracking, step logging out of the box

---

## Design Philosophy

### 1. Explicit Over Magic
No hidden auto-wiring. Every component is explicitly configured. If an agent calls a tool, you see exactly where and why.

### 2. Composable, Not Opinionated
The `core` module is pure Python with zero mandatory dependencies. LangGraph, Qdrant, OpenAI — all are optional integrations, not requirements.

### 3. Schema-First
Every interface (tool inputs/outputs, agent state, memory schema, API payloads) is defined with strict types before implementation. Prevents entire classes of bugs.

### 4. Production-Ready From Day One
Retries, timeouts, cost budgets, circuit breakers, human-in-the-loop, and audit logging are built-in — not afterthoughts.

### 5. Observable By Default
Every agent step, tool call, LLM invocation, and memory operation emits structured events. You never wonder "what is the agent doing right now?"

### 6. Developer Experience First
The Web UI exists so that non-engineers can configure, run, and monitor agents without writing code. But engineers get full programmatic control of everything the UI does.

---

## Library Name & Namespace

```
Package name:  maldaagenticore
Import as:     import agenticore as ag
PyPI slug:     maldaagenticore
CLI command:   agenticore
```

---

## Core Value Propositions

| Other Libraries | AgentiCore |
|----------------|-----------|
| Lock you into one reasoning pattern | Support all patterns, switchable at runtime |
| Memory is bolted on | Memory is a first-class design concern |
| No Web UI — code only | Full Web UI with visual builder |
| Framework-heavy (forces LangChain/LangGraph) | Framework-agnostic core, optional integrations |
| Hard to extend tools | Plugin system + decorator-based tool registration |
| Poor observability | Structured tracing, cost tracking, step logging built-in |
| No multi-language vision | Python first, then Rust/C++/JS with shared protocols |

---

## Quick Concept Demo (Target API)

```python
import agenticore as ag

# 1. Define a tool with a decorator
@ag.tool(description="Search the web for current information")
def search_web(query: str, max_results: int = 5) -> list[ag.SearchResult]:
    ...

# 2. Build an agent
agent = (
    ag.AgentBuilder()
    .name("ResearchAgent")
    .llm(ag.LLM.GPT4O)
    .reasoning(ag.ReAct)
    .tools([search_web, ag.tools.CodeExecutor()])
    .memory(ag.memory.Qdrant(url="localhost:6333"))
    .max_steps(20)
    .build()
)

# 3. Run it
result = agent.run("Summarize key AI releases from Q1 2026")
print(result.output)
print(result.trace)   # Full step-by-step trace
print(result.cost)    # Token cost in USD

# 4. Or launch the Web UI
ag.serve(agents=[agent], port=8080)
```

---

## Documentation Index

| Document | Description |
|----------|-------------|
| [README.md](./README.md) | This file — overview and quick start |
| [docs/architecture/01-system-overview.md](./docs/architecture/01-system-overview.md) | High-level system architecture |
| [docs/architecture/02-design-patterns.md](./docs/architecture/02-design-patterns.md) | All design patterns used and why |
| [docs/architecture/03-repository-structure.md](./docs/architecture/03-repository-structure.md) | Full repo layout with purpose of every folder |
| [docs/architecture/04-core-abstractions.md](./docs/architecture/04-core-abstractions.md) | Agent, Tool, Memory, State — the core interfaces |
| [docs/architecture/05-plugin-system.md](./docs/architecture/05-plugin-system.md) | How the plugin/extension system works |
| [docs/architecture/06-request-lifecycle-sequence.md](./docs/architecture/06-request-lifecycle-sequence.md) | End-to-end request lifecycle and sequence diagram |
| [docs/webui/01-webui-overview.md](./docs/webui/01-webui-overview.md) | Web UI design, screens, and data flow |
| [docs/webui/02-webui-components.md](./docs/webui/02-webui-components.md) | UI component breakdown |
| [docs/api/01-rest-api-design.md](./docs/api/01-rest-api-design.md) | REST API that backs the Web UI |
| [docs/api/02-websocket-protocol.md](./docs/api/02-websocket-protocol.md) | Real-time agent execution WebSocket protocol |
| [docs/guides/01-getting-started.md](./docs/guides/01-getting-started.md) | 5-minute quickstart guide |
| [docs/guides/02-building-custom-tools.md](./docs/guides/02-building-custom-tools.md) | How to build and register custom tools |
| [docs/guides/03-building-custom-agents.md](./docs/guides/03-building-custom-agents.md) | How to build custom agent types |
| [docs/guides/04-memory-configuration.md](./docs/guides/04-memory-configuration.md) | Configuring all memory backends |
| [docs/guides/05-multi-agent-setup.md](./docs/guides/05-multi-agent-setup.md) | Setting up multi-agent systems |
| [docs/guides/06-production-deployment.md](./docs/guides/06-production-deployment.md) | Deploying AgentiCore to production |
| [docs/guides/07-start-here-building-your-first-agent.md](./docs/guides/07-start-here-building-your-first-agent.md) | Practical path for building your first custom agent |
| [docs/guides/08-publishing-to-pypi.md](./docs/guides/08-publishing-to-pypi.md) | Step-by-step guide for publishing AgentiCore to PyPI |

> Note: some older sections in this README still describe the original design target. Use the docs above and the code under `src/agenticore/` as the source of truth for the current implementation.

---

## Roadmap

### Phase 0 — Design (Current)
- [x] Architecture design documents
- [x] Design pattern decisions
- [x] Repository structure planning
- [x] Web UI wireframes and data flow
- [x] API contract design
- [ ] Core interface definitions (TypedDict / Protocol / ABC)

### Phase 1 — Foundation
- [ ] Core abstractions: `Agent`, `Tool`, `Memory`, `State`
- [ ] ReAct reasoning engine
- [ ] In-memory state and working memory
- [ ] Tool registry with JSON Schema validation
- [ ] OpenAI LLM integration
- [ ] Basic structured logging/tracing
- [ ] CLI: `agenticore run`

### Phase 2 — Memory & Reasoning
- [ ] Plan-and-Execute reasoning
- [ ] Reflection reasoning
- [ ] Qdrant semantic memory (RAG)
- [ ] Episodic memory with PostgreSQL
- [ ] Memory summarization (auto context management)
- [ ] Anthropic + Ollama LLM integrations

### Phase 3 — Multi-Agent
- [ ] Orchestrator → Worker pattern
- [ ] Parallel fan-out with async tool execution
- [ ] Agent communication protocol
- [ ] LangGraph integration (optional backend)

### Phase 4 — Web UI
- [ ] FastAPI backend (REST + WebSocket)
- [ ] Agent builder UI
- [ ] Tool creator UI
- [ ] Real-time run monitor
- [ ] Trace/step inspector
- [ ] Memory explorer

### Phase 5 — Plugin System & Ecosystem
- [ ] Plugin loader and registry
- [ ] Plugin SDK for third-party tools
- [ ] Built-in plugins: web search, code executor, file system, HTTP
- [ ] Plugin marketplace UI

### Phase 6 — Production Hardening
- [ ] Cost tracking and budget limits
- [ ] Human-in-the-loop interrupts
- [ ] Rate limiting and circuit breakers
- [ ] Full test suite (unit + integration + e2e)
- [ ] Docker Compose deployment template
- [ ] Kubernetes Helm chart

---

## Multi-Language Vision

AgentiCore (Python) is the reference implementation. The same design patterns, protocols, and Web UI will be ported to:

| Language | Package Name | Target Phase |
|----------|-------------|-------------|
| **Python** | `agenticore` | Primary (Now) |
| **Rust** | `agenticore-rs` | Phase 2 (after Python stable) |
| **C++** | `agenticore-cpp` | Phase 3 |
| **JavaScript/TypeScript** | `@agenticore/js` | Phase 2 (parallel with Rust) |

All language implementations share:
- Same tool schema format (JSON Schema)
- Same agent state wire format (JSON)
- Same REST/WebSocket API protocol
- Same Web UI (served from Python, connects to any backend)

---

## License & Contributing

- **License:** Apache 2.0 (permissive, commercial-friendly)
- **Contributing:** See [CONTRIBUTING.md](./CONTRIBUTING.md)
- **Code of Conduct:** See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
