# AI Conversational Agent

Modular AI conversational agent for building context-aware,
task-oriented chatbots and conversational automation.

Table of Contents
- Overview
- Features
- Quick Start
- Usage
- Configuration
- Architecture
- Development
- Testing
- Contributing
- License
- Contact

Overview
--------
This repository contains a modular, extensible conversational agent framework
designed for rapid prototyping and production deployment of chatbots and
task-oriented agents. The codebase focuses on clear separation of concerns
(input handling, NLU, dialogue management, action execution, and persistence)
 and provides CLI tooling and configuration-driven workflows to simplify automation.

Features
--------
- Declarative configuration (JSON/YAML) for manifests and pipelines
- Context-aware, multi-turn dialogue support
- Modular NLU / policy / action components for easy extension
- Dry-run and debug modes for safe testing
- Optional persistence layer for session and conversation state
- CLI for local testing and integration into automation pipelines
- Structured logging and exit codes for CI/cron usage

Quick Start
-----------
Prerequisites
- Python 3.9+ (or the version your project requires)
- Optional: virtual environment tool (venv, pipenv, poetry)

Local install (recommended)
```bash
git clone https://github.com/hasnatsakil/ai-conversational-agent.git
cd ai-conversational-agent
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run (example)

# Dry-run: validate pipeline and config without connecting to models or external services
python -m ai_conversational_agent --config config/config.json --dry-run

# Start agent in interactive mode
python -m ai_conversational_agent --config config/config.json --interactive

# Run agent as a service (example)
python -m ai_conversational_agent --config config/config.json --host 0.0.0.0 --port 8080

Usage

The project exposes a CLI and programmatic API.

Common CLI options

• --config / -c : path to JSON/YAML pipeline config (required)
• --interactive : run in REPL-style interactive console
• --dry-run : validate configuration and pipelines without executing actions
• --log / -l : path to log file
• --debug : enable debug logging

Programmatic usage (example)

from ai_conversational_agent import Agent, AgentConfig

cfg = AgentConfig.from_file("config/config.json")
agent = Agent(cfg)
response = agent.handle_message(user_id="user-123", text="What's the weather tomorrow?")

Configuration

The system is driven by a manifest describing models, pipelines, and action hooks. Example (simplified JSON):

{
  "nlp": {
    "provider": "openai",
    "model": "gpt-4",
    "api_key_env": "OPENAI_API_KEY"
  },
  "pipeline": [
    "tokenize",
    "intent_classify",
    "slot_fill",
    "policy",
    "action"
  ],
  "actions": {
    "get_weather": {
      "type": "http",
      "url": "https://api.weather/example",
      "method": "GET"
    }
  ]
}

Place your runtime/secret values in environment variables and point the config to templates where applicable.

Architecture

High-level components:

• Input adapters: REST, CLI, messaging platform connectors
• NLU: tokenization, intent classification, entity extraction (pluggable)
• Dialogue Manager: maintains session context and executes policies
• Action Executor: runs side effects (HTTP calls, DB updates, system commands)
• Storage: session store / conversation logs (filesystem, Redis, or DB)
• Observability: structured logs, metrics, traces (optional)

Development

• Follow the repository layout: src/ or ai_conversational_agent/ contains core modules
• Keep unit tests next to modules or under tests/
• Use pre-commit hooks and linting tools for consistent style

Common development commands

# install dev requirements
pip install -r requirements-dev.txt

# run lint
flake8 src tests

# run tests
pytest -q

Testing

• Unit tests cover NLU components, policy logic, and action execution mocks
• Integration tests exercise full pipeline with sandboxed connectors
• Add VCR or recorded fixtures for external API interactions

Contributing

Contributions are welcome. Follow these steps:

1. Fork the repository.
2. Create a feature branch: git checkout -b feat/your-feature
3. Run tests and linters locally.
4. Open a PR with a clear title and description; reference any related issues.

Guidelines

• Keep changes small and focused.
• Add or update tests for new behavior.
• Document public APIs and CLI options.

License

This project is released under the MIT License. See LICENSE for details.

Contact

Maintainer: hasnatsakil

• GitHub: https://github.com/hasnatsakil

Acknowledgements

• (Optional) mention major libraries, datasets, or inspirations.