# {{ project_name }}

{{ description }}

**Domain:** {{ domain }}  
**Generated by:** ABI-Core CLI  
**Version:** {{ version | default('0.1.0') }}

## Overview

This project is built using the ABI-Core framework and includes:

- **Multi-agent architecture** with semantic layer integration
{% if with_semantic_layer %}
- **Semantic Layer Service** for intelligent agent discovery and routing
{% endif %}
{% if with_guardian %}
- **Guardian Security Service** with OPA policy enforcement
{% endif %}
- **Domain-specific optimizations** for {{ domain }}

## Architecture

```
{{ project_name }}
├── agents/                 # Agent implementations
├── services/              # Core services
{% if with_semantic_layer %}
│   ├── semantic_layer/    # Semantic layer service
│   │   ├── mcp_server/    # MCP server with agent cards
│   │   └── embedding_mesh/ # Embedding and vector operations
{% endif %}
{% if with_guardian %}
│   └── guardian/          # Security and policy enforcement
│       ├── opa/           # Open Policy Agent policies
│       └── guard_core/    # Guardian implementation
{% endif %}
├── policies/              # System policies
├── config/                # Configuration files
└── .abi/                  # ABI runtime configuration
```

## Features

### Core Features
- **Agent-to-Agent Communication** via MCP protocol
- **Semantic Agent Discovery** using natural language queries
- **Policy-based Security** with OPA integration
- **Real-time Validation** of agent interactions

{% if domain == 'finance' %}
### Finance Domain Features
- **Compliance Validation** for financial operations
- **Risk Assessment** with configurable thresholds
- **Transaction Auditing** with full traceability
- **Regulatory Policy Enforcement**
{% elif domain == 'healthcare' %}
### Healthcare Domain Features
- **HIPAA Compliance** validation
- **PHI Protection** with access controls
- **Patient Data Auditing** with privacy safeguards
- **Healthcare-specific Policies**
{% endif %}

{% if with_semantic_layer %}
### Semantic Layer
The semantic layer provides intelligent agent discovery and routing:

- **Agent Registration** via JSON agent cards
- **Semantic Search** using embedding-based similarity
- **Dynamic Routing** based on capability matching
- **Vector Database** integration with Weaviate

#### Agent Cards
Agent cards are stored in `services/semantic_layer/mcp_server/agent_cards/` and define:
- Agent capabilities and skills
- Supported tasks and functions
- Metadata and configuration
- Security and access policies
{% endif %}

{% if with_guardian %}
### Guardian Security
The Guardian service provides comprehensive security:

- **Policy Evaluation** using Open Policy Agent (OPA)
- **Risk Assessment** with multi-dimensional scoring
- **Emergency Response** with automatic threat mitigation
- **Audit Logging** with cryptographic signatures

#### Security Policies
Policies are defined in `services/guardian/opa/policies/` using Rego language:
- Access control rules
- Risk assessment logic
- Domain-specific compliance checks
- Emergency response triggers
{% endif %}

## Quick Start

### Prerequisites
- Docker and Docker Compose
- Python 3.11+
- ABI-Core CLI (`pip install abi-core`)

### Installation

1. **Clone and setup:**
   ```bash
   cd {{ project_dir }}
   pip install -r requirements.txt
   ```

2. **Start services:**
   ```bash
   docker-compose up -d
   ```

3. **Initialize Ollama models:**
   ```bash
   docker exec {{ project_dir }}-ollama ollama pull {{ model_name | default('qwen2.5:3b') }}
   {% if with_semantic_layer %}
   docker exec {{ project_dir }}-ollama ollama pull {{ embedding_model | default('nomic-embed-text:v1.5') }}
   {% endif %}
   ```

4. **Verify services:**
   ```bash
   # Main application
   curl http://localhost:8000/health
   
   {% if with_semantic_layer %}
   # Semantic layer
   curl http://localhost:10100/health
   {% endif %}
   
   {% if with_guardian %}
   # Guardian security
   curl http://localhost:11438/health
   
   # OPA policies
   curl http://localhost:8181/v1/data
   {% endif %}
   ```

### Development

1. **Add new agents:**
   ```bash
   abi-core add agent --name MyAgent --description "Custom agent"
   ```

2. **Register agents:**
   ```bash
   # Agent cards are automatically discovered from agent_cards/ directory
   # Or register dynamically via API:
   curl -X POST http://localhost:10100/v1/register_agent \
     -H "Content-Type: application/json" \
     -d @path/to/agent_card.json
   ```

3. **Test semantic search:**
   ```bash
   curl -X POST http://localhost:10100/v1/tools/find_agent \
     -H "Content-Type: application/json" \
     -d '{"query": "analyze financial data"}'
   ```

{% if with_guardian %}
4. **Test security validation:**
   ```bash
   curl -X POST http://localhost:11438/v1/tools/validate_semantic_access \
     -H "Content-Type: application/json" \
     -d '{
       "agent_id": "test_agent",
       "agent_card": {"id": "test", "metadata": {"status": "active"}},
       "request_metadata": {"tool_name": "test_tool"}
     }'
   ```
{% endif %}

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ABI_ROLE` | {{ project_name }} | ABI role identifier |
| `MODEL_NAME` | {{ model_name | default('qwen2.5:3b') }} | Primary LLM model |
| `OLLAMA_HOST` | http://localhost:11434 | Ollama service URL |
{% if with_semantic_layer %}
| `SEMANTIC_LAYER_URL` | http://localhost:10100 | Semantic layer service URL |
| `EMBEDDING_MODEL` | {{ embedding_model | default('nomic-embed-text:v1.5') }} | Embedding model for semantic search |
| `WEAVIATE_URL` | http://localhost:8080 | default('8080') }} | Weaviate vector database URL |
{% endif %}
{% if with_guardian %}
| `GUARDIAN_URL` | http://localhost:11438 | Guardian security service URL |
| `OPA_URL` | http://localhost:8181 | Open Policy Agent URL |
| `MAX_RISK_THRESHOLD` | {{ max_risk_threshold | default('0.7') }} | Maximum allowed risk score |
{% endif %}

{% if domain == 'finance' %}
### Finance Domain Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `COMPLIANCE_REQUIRED` | true | Require compliance validation |
| `AUDIT_ALL_TRANSACTIONS` | true | Audit all financial transactions |
| `MAX_TRANSACTION_AMOUNT` | 10000.0 | Maximum transaction without approval |
{% elif domain == 'healthcare' %}
### Healthcare Domain Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `HIPAA_COMPLIANCE` | true | Enable HIPAA compliance checks |
| `PHI_PROTECTION` | true | Enable PHI protection |
| `AUDIT_PATIENT_ACCESS` | true | Audit all patient data access |
{% endif %}

## API Reference

### Main Application
- `GET /` - Service status
- `GET /health` - Health check
- `GET /v1/agents` - List registered agents

{% if with_semantic_layer %}
### Semantic Layer (`http://localhost:10100`)
- `POST /v1/tools/find_agent` - Find agents by query
- `GET /v1/agents` - List all agents
- `POST /v1/register_agent` - Register new agent
- `DELETE /v1/agents/{agent_id}` - Unregister agent
{% endif %}

{% if with_guardian %}
### Guardian Security (`http://localhost:11438`)
- `POST /v1/tools/validate_semantic_access` - Validate access
- `GET /v1/tools/get_guardian_status` - Guardian status
- `GET /v1/tools/get_security_metrics` - Security metrics
- `POST /v1/tools/block_agent` - Block agent
- `POST /v1/tools/unblock_agent` - Unblock agent
{% endif %}

## Monitoring and Logs

### Log Locations
- Application logs: `./logs/`
- Emergency logs: `./services/guardian/emergency_logs/`
- Docker logs: `docker-compose logs -f [service_name]`

### Health Checks
All services include health check endpoints for monitoring:
```bash
# Check all services
docker-compose ps
```

### Metrics
{% if with_guardian %}
Security metrics are available via Guardian API:
```bash
curl http://localhost:11438/v1/tools/get_security_metrics
```
{% endif %}

## Security

{% if with_guardian %}
### Policy Management
- Policies are defined in Rego language
- Real-time policy evaluation via OPA
- Emergency response with automatic blocking
- Comprehensive audit logging

### Risk Assessment
Multi-dimensional risk scoring based on:
- Agent trust level
- Request patterns
- Temporal factors
- Domain-specific rules
{% endif %}

### Best Practices
1. **Agent Registration**: Always register agents with proper metadata
2. **Policy Updates**: Test policies in development before production
3. **Monitoring**: Monitor security metrics and emergency logs
4. **Access Control**: Use principle of least privilege

## Troubleshooting

### Common Issues

1. **Services not starting:**
   ```bash
   docker-compose down
   docker-compose up -d --build
   ```

2. **Ollama models not available:**
   ```bash
   docker exec {{ project_dir }}-ollama ollama list
   docker exec {{ project_dir }}-ollama ollama pull [model_name]
   ```

{% if with_semantic_layer %}
3. **Agent cards not loading:**
   ```bash
   # Check agent cards directory
   ls -la services/semantic_layer/mcp_server/agent_cards/
   
   # Verify JSON format
   python -m json.tool services/semantic_layer/mcp_server/agent_cards/example_agent.json
   ```
{% endif %}

{% if with_guardian %}
4. **Policy evaluation errors:**
   ```bash
   # Check OPA logs
   docker-compose logs {{ project_dir }}-opa
   
   # Test policy syntax
   docker exec {{ project_dir }}-opa opa test /policies
   ```
{% endif %}

### Support
- **Documentation**: [ABI-Core Docs](https://github.com/Joselo-zn/abi-core)
- **Issues**: [GitHub Issues](https://github.com/Joselo-zn/{{ project_dir }}/issues)
- **Community**: [Discord/Slack Channel]

## License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Generated by ABI-Core CLI v{{ cli_version | default('1.0.0') }}