Metadata-Version: 2.4
Name: Amsha
Version: 3.0.0
Summary: Amsha is a lightweight library designed to provide common configuration and helper utilities for CrewAI orchestration. It serves as a foundational component for building scalable and maintainable AI agent systems
License-Expression: MIT
Project-URL: Repository, https://github.com/NikhilVijayakumar/Amsha
Requires-Python: <3.14,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML==6.0.3
Requires-Dist: crewai==1.15.18
Requires-Dist: crewai-tools==1.15.18
Requires-Dist: dependency-injector==4.48.2
Requires-Dist: pandas==2.3.2
Requires-Dist: openpyxl==3.1.5
Requires-Dist: pydantic==2.11.9
Requires-Dist: docling==2.53.0
Requires-Dist: psutil==7.1.3
Requires-Dist: chardet==5.2.0
Requires-Dist: nvidia-ml-py==13.580.82
Requires-Dist: litellm>=1.99.0
Provides-Extra: research
Requires-Dist: scikit-learn>=1.3.0; extra == "research"
Requires-Dist: matplotlib>=3.7.0; extra == "research"
Requires-Dist: seaborn>=0.12.0; extra == "research"
Requires-Dist: jupyter>=1.0.0; extra == "research"
Dynamic: license-file

# Amsha

**Amsha** is a lightweight library for **CrewAI** orchestration. It provides configuration management, agent/task definition, knowledge integration, and monitoring utilities — letting you define crews in YAML and run them with minimal boilerplate.

---

## Key Features

### Crew Forge & Orchestration
- **File-Based**: Define agents and tasks in version-controlled YAML files.
- **Flows**: Multi-crew pipelines via CrewAI `Flow` — ordered execution with shared state.
- **Memory & Checkpointing**: Opt-in per crew (`memory: true`, `checkpoint:` config) — off by default.
- **Tracing**: Opt-in CrewAI native tracing (`tracing: true`) — off by default, sends prompts to CrewAI's hosted dashboard.

### Tools & MCP
- **Tool Registry**: Agents and tasks declare tools by name in YAML (`tools: [file_read, directory_read]`). Ships with built-in tools; extend with `register_tool()`.
- **MCP Servers**: Agents connect to MCP servers via structured YAML (`mcp_servers:`) — stdio, HTTP, or SSE transports.

### Knowledge Management
- **Multi-Format**: Docling-powered sources for Markdown, PDF, DOCX, HTML, XLSX, PPTX, images.
- **JSON Native**: CrewAI's `JSONKnowledgeSource` for structured JSON files.
- **Auto-Routing**: `.json` paths route to JSON source; everything else to Docling.

### Skills
- **Runtime Skills**: Agents reference CrewAI skills by name in YAML (`skills: ["domain-skills"]`). Amsha resolves names to skill search paths.

### Monitoring & Observability
- **CrewPerformanceMonitor**: Real-time CPU/GPU/memory tracking during execution.
- **AmshaEventListener**: Event-bus subscriber for per-task, per-LLM-call, per-tool-call lifecycle logs — local, no cloud dependency.
- **Contribution Analysis & Reporting**: Feature attribution analysis and Excel report generation.

### LLM Factory
- **Unified Config**: One YAML for all LLM providers (Ollama, LM Studio, OpenRouter, Gemini).
- **Purpose Profiles**: Creative (high temperature) vs. Evaluation (deterministic) modes.

---

## Installation

```bash
pip install amsha
```

Amsha currently declares Docling as a runtime dependency. Until the first PyPI release is published, use the existing source installation. See [release guidance](docs/releasing.md) for the publishing process.

---

## Migration to 3.0

**Migration:** Azure-qualified LLM models (`azure/` and `azure_ai/`) are no longer supported. Configure another provider before upgrading to the next major version.

## Quick Start

```python
from amsha.crew_forge.orchestrator.file.amsha_crew_file_application import AmshaCrewFileApplication
from amsha.llm_factory.domain.model.llm_type import LLMType

config_paths = {
    "app": "config/app_config.yaml",
    "job": "config/job_config.yaml",
    "llm": "config/llm_config.yaml"
}

app = AmshaCrewFileApplication(config_paths=config_paths, llm_type=LLMType.CREATIVE)
```

### Agent YAML with Tools, Skills, and MCP

```yaml
# agents/researcher_agent.yaml
agent:
  role: "Researcher"
  goal: "Research topics thoroughly"
  backstory: "Expert researcher with access to web and files"
  tools: [file_read, directory_read]
  skills: ["domain-skills"]
  mcp_servers:
    - transport: stdio
      command: python
      args: [servers/db_server.py]
      env:
        DB_HOST: localhost
```

### Crew Config with Memory, Checkpointing, Tracing

```yaml
# job_config.yaml
crews:
  research_crew:
    memory: true
    checkpoint:
      enabled: true
      provider: json
      location: "./.Amsha/execution/checkpoints"
    tracing: true      # opt-in: sends prompts to CrewAI dashboard
    steps:
      - task_key: research_task
        agent_key: researcher_agent
```

### Multi-Crew Pipeline

```yaml
pipeline:
  - "research_crew"
  - "writing_crew"
```

```python
outputs = app.run_pipeline({"brief": "..."})
```

---

## Configuration Structure

- **`app_config.yaml`**: Global settings (directories, output paths).
- **`job_config.yaml`**: Crew definitions, steps, pipelines, knowledge sources.
- **`llm_config.yaml`**: LLM provider, model, API keys, creative/evaluation profiles.

---

## Testing

```bash
python -m pytest tests/unit/
```

With coverage:
```bash
python -m pytest tests/unit/ --cov=amsha --cov-report=term-missing
```

---

## Documentation

- [Crew Forge](docs/feature/crew_forge/About.md) — orchestration, YAML schema, tools, MCP, flows
- [Crew Monitor](docs/feature/crew_monitor/About.md) — performance monitoring, event observability
- [LLM Factory](docs/feature/llm_factory/About.md) — LLM configuration and profiles

## License

Copyright (c) 2025 Nikhil Vijayakumar. Licensed under the [MIT License](LICENSE).
