Metadata-Version: 2.1
Name: mana-agent
Version: 0.15.2
Summary: Autonomous multi-agent AI software engineering platform for repository understanding, planning, coding, debugging, testing, and verified task execution.
License: MIT
Requires-Python: <=3.15.2,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer<1.0.0,>=0.6.0
Requires-Dist: rich<15.0,>=12.0
Requires-Dist: textual<1.0.0,>=0.80.0
Requires-Dist: prompt_toolkit<4.0,>=3.0
Requires-Dist: fastapi<1.0,>=0.110
Requires-Dist: uvicorn<1.0,>=0.27
Requires-Dist: python-multipart<1.0,>=0.0.9
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: pydantic-settings<3.0,>=2.0
Requires-Dist: python-dotenv<3.0,>=1.0
Requires-Dist: PyYAML<7.0,>=6.0
Requires-Dist: tomli<3.0,>=2.0; python_version < "3.11"
Requires-Dist: exceptiongroup<2.0,>=1.2; python_version < "3.11"
Requires-Dist: tzdata>=2025.2
Requires-Dist: mcp<2.0,>=1.0
Requires-Dist: openai<3.0.0,>=2.26.0
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: anthropic<1.0.0,>=0.40.0
Requires-Dist: safety<3.0,>=2.0
Requires-Dist: python-docx<2.0,>=1.1
Requires-Dist: openpyxl<4.0,>=3.1
Requires-Dist: pypdf<7.0,>=4.0
Requires-Dist: reportlab<5.0,>=4.0
Requires-Dist: redis<5.0.0,>=4.5.0
Requires-Dist: rq<2.0.0,>=1.10.0
Requires-Dist: tenacity<9.0.0,>=8.0.0
Requires-Dist: cryptography<51.0,>=49.0.0
Requires-Dist: websockets<16,>=12
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
Requires-Dist: packaging>=26.3; extra == "dev"
Provides-Extra: browser
Requires-Dist: playwright<2.0,>=1.45; extra == "browser"
Provides-Extra: teach-desktop
Requires-Dist: pynput<2.0,>=1.7; extra == "teach-desktop"
Requires-Dist: pyobjc-framework-Quartz<13,>=10; sys_platform == "darwin" and extra == "teach-desktop"
Requires-Dist: pyobjc-framework-Cocoa<13,>=10; sys_platform == "darwin" and extra == "teach-desktop"
Requires-Dist: pyobjc-framework-ApplicationServices<13,>=10; sys_platform == "darwin" and extra == "teach-desktop"
Provides-Extra: mem0
Requires-Dist: mem0ai<3.0,>=2.0; extra == "mem0"
Requires-Dist: keyring<26.0,>=24.0; extra == "mem0"
Provides-Extra: supermemory
Requires-Dist: supermemory<6,>=5.0.1; extra == "supermemory"
Requires-Dist: keyring<26.0,>=24.0; extra == "supermemory"
Provides-Extra: acp
Requires-Dist: agent-client-protocol<2.0.0,>=1.0.0; extra == "acp"
Provides-Extra: a2a
Requires-Dist: a2a-sdk[http-server]<2.0,>=1.1; extra == "a2a"
Provides-Extra: protocols
Requires-Dist: agent-client-protocol<2.0.0,>=1.0.0; extra == "protocols"
Requires-Dist: a2a-sdk[http-server]<2.0,>=1.1; extra == "protocols"
Provides-Extra: execution-kubernetes
Requires-Dist: kubernetes<35,>=30; extra == "execution-kubernetes"
Provides-Extra: execution-modal
Requires-Dist: modal<2,>=0.64; extra == "execution-modal"
Provides-Extra: execution
Requires-Dist: kubernetes<35,>=30; extra == "execution"
Requires-Dist: modal<2,>=0.64; extra == "execution"
Provides-Extra: live
Requires-Dist: sounddevice<1.0,>=0.5; extra == "live"
Requires-Dist: numpy<3.0,>=1.24; extra == "live"
Provides-Extra: dashboard
Requires-Dist: streamlit<2.0,>=1.38; extra == "dashboard"
Requires-Dist: plotly<6,>=5.22; extra == "dashboard"
Requires-Dist: pandas<3,>=2.2; extra == "dashboard"
Provides-Extra: automations
Requires-Dist: apscheduler<4,>=3.10; extra == "automations"
Provides-Extra: observability
Requires-Dist: opentelemetry-sdk<2,>=1.27; extra == "observability"
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.27; extra == "observability"
Provides-Extra: email
Requires-Dist: google-api-python-client<3.0,>=2.0; extra == "email"
Requires-Dist: google-auth-oauthlib<2.0,>=1.2; extra == "email"
Requires-Dist: keyring<26.0,>=24.0; extra == "email"
Provides-Extra: full
Requires-Dist: playwright<2.0,>=1.45; extra == "full"
Requires-Dist: pynput<2.0,>=1.7; sys_platform != "linux" and extra == "full"
Requires-Dist: pyobjc-framework-Quartz<13,>=10; sys_platform == "darwin" and extra == "full"
Requires-Dist: pyobjc-framework-Cocoa<13,>=10; sys_platform == "darwin" and extra == "full"
Requires-Dist: pyobjc-framework-ApplicationServices<13,>=10; sys_platform == "darwin" and extra == "full"
Requires-Dist: streamlit<2.0,>=1.38; extra == "full"
Requires-Dist: plotly<6,>=5.22; extra == "full"
Requires-Dist: pandas<3,>=2.2; extra == "full"
Requires-Dist: apscheduler<4,>=3.10; extra == "full"
Requires-Dist: opentelemetry-sdk<2,>=1.27; extra == "full"
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.27; extra == "full"
Requires-Dist: google-api-python-client<3.0,>=2.0; extra == "full"
Requires-Dist: google-auth-oauthlib<2.0,>=1.2; extra == "full"
Requires-Dist: keyring<26.0,>=24.0; extra == "full"
Requires-Dist: mem0ai<3.0,>=2.0; extra == "full"
Requires-Dist: supermemory<6,>=5.0.1; extra == "full"
Requires-Dist: agent-client-protocol<2.0.0,>=1.0.0; extra == "full"
Requires-Dist: a2a-sdk[http-server]<2.0,>=1.1; extra == "full"
Requires-Dist: sounddevice<1.0,>=0.5; extra == "full"
Requires-Dist: numpy<3.0,>=1.24; extra == "full"

# Mana-Agent

Repository execution uses MainAgent → CodingAgent → deterministic ToolRunner. Repository knowledge is shared through the persistent [Repository Evidence Board](docs/regressions/repository-evidence-orchestration.md); investigation and understanding are TaskBoard tasks that use the selected coding engine.
Execution activity exposes commands, working directories, live output, observed
diffs, and retained operation details. External Codex keeps its own tool loop
with explicit backend provenance. See the [execution and verification contract](docs/regressions/hierarchical-tool-execution.md).

Inference uses Mana's native OpenAI Responses, Chat Completions and Anthropic
Messages adapters. Model capabilities come from scoped evidence and explicit
user overrides. Repository search needs no vector index or embedding credential.
See [configuration and user-owned acceptance](docs/native-llm-engine.md).

<p align="center">
  <img src="https://raw.githubusercontent.com/manaplatform/mana-agent/refs/heads/main/logo.png" alt="Mana-Agent" width="100%" />
</p>

<p align="center">
  <strong>Think beyond prompts. Build beyond boundaries.</strong>
</p>

<p align="center">
  Your AI-powered execution workspace.<br>
  One goal. Multiple agents. Real tools. Verified results.
</p>

<p align="center">
  <a href="https://www.python.org/"><img alt="Python" src="https://img.shields.io/badge/Python-3.10--3.15.2-3776AB?logo=python&logoColor=white" /></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/License-MIT-22A06B" /></a>
  <a href="https://github.com/manaplatform/mana-agent"><img alt="GitHub" src="https://img.shields.io/badge/GitHub-Mana--Agent-181717?logo=github" /></a>
</p>

<p align="center">
  <a href="README.md" lang="en">English</a> · <a href="README.ar.md" lang="ar" dir="rtl">العربية</a> · <a href="README.bn.md" lang="bn">বাংলা</a> · <a href="README.br.md" lang="br">Brezhoneg</a> · <a href="README.bs.md" lang="bs">Bosanski</a> · <a href="README.da.md" lang="da">Dansk</a> · <a href="README.de.md" lang="de">Deutsch</a> · <a href="README.es.md" lang="es">Español</a> · <a href="README.fa.md" lang="fa" dir="rtl">فارسی</a> · <a href="README.fr.md" lang="fr">Français</a> · <a href="README.gr.md" lang="el">Ελληνικά</a> · <a href="README.it.md" lang="it">Italiano</a> · <a href="README.ja.md" lang="ja">日本語</a> · <a href="README.ko.md" lang="ko">한국어</a> · <a href="README.no.md" lang="no">Norsk</a> · <a href="README.pl.md" lang="pl">Polski</a> · <a href="README.ru.md" lang="ru">Русский</a> · <a href="README.th.md" lang="th">ไทย</a> · <a href="README.tr.md" lang="tr">Türkçe</a> · <a href="README.uk.md" lang="uk">Українська</a> · <a href="README.vi.md" lang="vi">Tiếng Việt</a> · <a href="README.zh.md" lang="zh-Hans">简体中文</a> · <a href="README.zht.md" lang="zh-Hant">繁體中文</a>
</p>

<p align="center">
  <a href="#quick-start">Get Started</a> ·
  <a href="#what-can-mana-agent-do">Capabilities</a> 
</p>

---

## What if your AI could do more than answer?

Most AI tools stop at the answer.

You ask a question. They generate a response. Then you're left to figure out what to do next.

**Mana-Agent is built for what happens after the answer.**

It can understand your goals, explore your environment, plan actions, coordinate specialized agents, use real tools, and verify outcomes.

Not just for writing code.

For researching, building, debugging, managing, automating, and solving complex tasks across connected systems.

For unresolved coding bugs, the Main Model can select bounded, version-aware web/GitHub research after local investigation and return sourced findings to the same coding task. Both coding engines use the existing Coding Activity stream. See [coding research configuration and recovery](docs/regressions/coding-bug-research.md).

**You define the destination. Mana-Agent helps navigate the journey.**

## Meet Mana-Agent

Mana-Agent is an open-source, Python-based AI agent orchestration platform combining an autonomous execution loop, specialized agents, persistent task management, supervised tool execution, and extensible integrations.

It brings multiple capabilities into one coordinated environment:

- **Understand:** Analyze repositories, documents, APIs, and available evidence before taking action.
- **Decide:** Select suitable models, agents, tools, and execution strategies.
- **Execute:** Use coding tools, browser automation, external services, and connected systems.
- **Coordinate:** Distribute work among specialized agents while tracking dependencies and progress.
- **Remember:** Reuse authorized context, decisions, and lessons across relevant tasks.
- **Verify:** Evaluate actual outcomes rather than treating tool completion as success.
- **Continue:** Replan, recover, or request human intervention when the goal remains unresolved.

The objective is simple:

**Make AI useful not only for thinking about work, but for carrying work through to a trustworthy result.**

## What can Mana-Agent do?

| Your challenge | What Mana-Agent can help with |
|---|---|
| "I don't understand this codebase." | Explore architecture, dependencies, execution flows, and relevant files. |
| "Something is broken." | Investigate symptoms, identify likely causes, propose fixes, and run verification. |
| "I want to build something complex." | Decompose goals, coordinate coding agents, manage dependencies, and review implementation. |
| "This task has too many steps." | Track progress through the autonomous loop, TaskBoard, and execution supervisor. |
| "I need information from an API." | Inspect API documentation, validate requests, and execute supported operations. |
| "I keep repeating this workflow." | Create automations or teach repeatable actions using Teach Mode. |
| "I want AI to work across tools." | Integrate browser, Git, SSH, email, Telegram, protocols, and external services. |
| "What happened during execution?" | Inspect activity, tools, decisions, errors, checkpoints, and artifacts. |

### One interface. Many kinds of work.

```text
> Explain how authentication works in this repository.

> Find why the latest deployment failed.

> Plan and implement a new feature, then run its tests.

> Read this API documentation and help me call the right endpoint.

> Analyze these files and produce an actionable report.

> Break this project into independent tasks and track progress.

> Review previous mistakes before attempting this operation again.
```

Mana-Agent is designed to support both focused questions and multi-step workflows.

---

## Quick Start

### 1. Install

Requires Python 3.10–3.14.

Recommended installation with pipx:

```bash
pipx install git+https://github.com/manaplatform/mana-agent.git
```

Or install directly from the repository:

```bash
git clone https://github.com/manaplatform/mana-agent.git
cd mana-agent

python3 -m venv .venv
source .venv/bin/activate

python -m pip install -e .
```

### 2. Configure

```bash
mana-agent --configure
```

Configure your model provider, credentials, model preferences, and supported capabilities. The setup CLI includes OpenAI-compatible providers such as xAI (Grok); see [provider configuration](docs/05-configuration.md#xai-grok) for setup details.

### 3. Start

```bash
cd /path/to/your/project
mana-agent
```

You're ready.

### Execution & Approval Modes

Mana-Agent supports three execution approval modes:

- `default`: Interactive approval behavior (prompts for mutating/consequential operations).
- `auto_approve_safe`: Automatically approves explicitly classified safe operations (e.g., non-destructive shell, test runs, linters, local git queries); prompts for destructive actions.
- `full_access`: Automatically approves all supported operations without interactive confirmation prompts while preserving operating-system boundaries and security controls.

```bash
# Enable Full Access Mode via CLI
mana-agent --full-access
mana-agent --approval-mode full_access

# Or set via environment variable
export MANA_AGENT_APPROVAL_MODE=full_access

# Or configure in ~/.mana/config.toml
# [execution]
# approval_mode = "full_access"
```

Start with a question about your repository, ask for an investigation, or describe something you want to accomplish.

**Your first task doesn't need to be complicated.**

Try:

```text
Analyze this project and explain its architecture,
main components, dependencies, and potential risks.
```

### 4. Explore the dashboard

```bash
mana-agent dashboard --root-dir .
```

The optional dashboard provides another way to interact with Mana-Agent, inspect activity, and manage workflows.

---
### Live agent activity

Textual chat, Rich terminal chat, and the dashboard show observable operations,
agent explanations when provided, and supported public provider summaries while
work is running. The Textual chat shows one inline execution stream per turn.
Expand an operation for its redacted command, available output, diff, and
provenance. The Rich terminal and dashboard keep their existing activity views.
Concurrent agents retain their task, attempt, and operation identities.
Verification is recorded independently of backend completion.

Use `/activity minimal`, `/activity normal` (default), or `/activity verbose` to
persist `MANA_ACTIVITY_VISIBILITY` through the existing user configuration.
`/activity` shows recent recorded activity. In Textual chat, **Ctrl+End** returns
to the latest output, **Ctrl+O** attaches a file, and **Esc** requests interruption
of the session’s active execution. Begin with `/` to find available commands and
press Tab to insert the selected command. Assistant replies offer **Copy mode**
for selecting the Markdown source. Activity details use the public projection,
which excludes private reasoning, credentials, prompts, and raw invocation arguments.

During an active TUI or dashboard turn, submit text to steer that execution.
The user row appears pending immediately and follows recorded delivery and
acknowledgement. Dashboard steering is text-only and requires the same runtime
to own the live session. Execution approvals appear above the Textual composer.
**Ctrl+G** focuses the choices. Plan Mode activity describes planning and artifact
saving. Its revision review and clarification forms use the existing workflow.

See [activity architecture, limitations, regression rules, and user verification](docs/regressions/agent-activity-visibility.md).

Use `/plan` to review a repository change before approving its exact revision. In
ordinary chat, describe the failure to start an evidence-based investigation.
See [AUTO, DEBUG, and PLAN](docs/plan-and-act-modes.md) for ordinary coding and exact revision approval.

## License

Mana-Agent is open source under the [MIT License](LICENSE).

---

<p align="center">
  <strong>Mana-Agent</strong><br>
  <em>From intention to execution. From execution to evidence.</em>
</p>

<p align="center">
  <a href="#quick-start">Get Started</a> ·
  <a href="https://github.com/manaplatform/mana-agent">GitHub</a> ·
  <a href="https://github.com/manaplatform/mana-agent/issues">Report an Issue</a> ·
  <a href="docs/">Explore the Docs</a>
</p>

<p align="center">
  <strong>Have a goal in mind? Start with Mana.</strong>
</p>
