Metadata-Version: 2.4
Name: mchat-core
Version: 0.1.1
Summary: Reusable core components for mchat
Author-email: jspv <jspvgithub@twinleaf.xyz>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: autogen>=0.9.2
Requires-Dist: autogen-agentchat>=0.6.1
Requires-Dist: autogen-ext[azure,openai]>=0.6.1
Requires-Dist: dynaconf>=3.2.11
Requires-Dist: playwright>=1.52.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=14.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.0.0; extra == "dev"
Requires-Dist: pytest-forked>=1.6.0; extra == "dev"
Requires-Dist: ruff>=0.8.4; extra == "dev"
Requires-Dist: toml>=0.10.2; extra == "dev"
Provides-Extra: tools
Requires-Dist: bs4>=0.0.2; extra == "tools"
Requires-Dist: chromadb>=1.0.12; extra == "tools"
Requires-Dist: fredapi>=0.5.2; extra == "tools"
Requires-Dist: pypdf>=5.6.0; extra == "tools"
Requires-Dist: tzlocal>=5.3.1; extra == "tools"
Dynamic: license-file

# mchat_core

A collection of convenience functions for using LLM models and autogen agents driven by configuration files. Primarily used in [MChat](https://github.com/jspv/mchat) but written to be useful in a variety of use cases.

---

## Installation and Usage

Dependencies are declared in `pyproject.toml`. Development and dependency management are primarily done using `uv`.

The `[tools]` dependency group includes additional requirements for bundled LLM Module tools. You only need these if you plan on using the provided tools.

### Optional Tools Dependencies

- With uv (recommended):
  - uv sync --group tools
- With pip (install only what you need - see pyproject.toml)
  - pip install tzlocal fredapi chromadb beautifulsoup4

### Running Tests

- Run all tests:
  - pytest
- Show skip reasons:
  - pytest -rs
- Run only the tools tests:
  - pytest -m tools -rs
- Exclude tools tests:
  - pytest -m "not tools"

Note: Tool tests are marked with the “tools” marker and will auto-skip if optional packages are not installed.

---

## Configuration

**Note:** This code is actively developed. Instructions and sample configs may become outdated.

**See the examples.ipynb notebook for more details**

Configuration is managed in three files:

- `settings.toml`
- `.secrets.toml` *(optional but recommended)*
- `agents.yaml`

Edit `settings.toml` to configure your application. Here’s a guide to the available options:

---

### Models

Sections should start with `models.` (with a period) and contain no other periods in the section name.  
Format: `models.type.model_id` — `model_id` will appear in list of available models

    [models.chat.gpt-4o]
    api_key = "@format {this.openai_api_key}"
    model = "gpt-4o"
    api_type = "open_ai"
    base_url = "https://api.openai.com/v1"

> NOTE: Image models and settings here are only for explicitly calling image models from prompts.
> The `generate_image` tool uses only the API key.

---

#### Required Fields

**Chat Models**
- `api_type`: "open_ai" or "azure"
- `model_type`: "chat"
- `model`: Name of the model
- `api_key`: Your key or Dynaconf lookup
- `base_url`: (if required by API)

**Azure Chat Models (additional)**
- `azure_endpoint`: URL for your endpoint
- `azure_deployment`: Deployment name for the model
- `api_version`: API version

**Image Models**
- `api_type`: "open_ai" or "azure"
- `model_type`: "image"
- `model`: Name of the model
- `size`: Size of images to generate
- `num_images`: Number of images to generate
- `api_key`: Your key or Dynaconf lookup

---

### Default Settings

- `default_model`: Default model to use
- `default_temperature`: Default temperature for generation
- `default_persona`: Default persona for generation

---

### Memory Model Configuration (Currently Disabled)

mchat can maintain conversational memory for long chats. When memory size exceeds model limits, conversations are summarized using a designated model (ideally, a cost-effective one).

Configurable properties:
- `memory_model`: Model ID used for memory (should match one in `models`)
- `memory_model_temperature`: Temperature for memory summarization
- `memory_model_max_tokens`: Token limit for memory model

---

### Secrets Configuration

Some sensitive config settings (like API keys) should be in `.secrets.toml`:

    # .secrets.toml
    # dynaconf_merge = true

    # Replace the following with your actual API keys
    # openai_models_api_key = "oai_ai_api_key_goes_here"
    # ms_models_api_key = "ms_openai_api_key_goes_here"

---

## Agents & Teams

mchat provides:
- A default persona
- Example agents: *linux computer* & *financial manager*
- Example teams: round-robin and selector

You can add more agents and teams at the top level in `agents.yaml` (same directory as this README), following the structure in `mchat/default_personas.yaml`.  
When configuring personas, the `extra_context` list lets you define multi-shot prompts—see the `linux computer` persona in `mchat/default_personas.json` for an example.

## Contributing

Thank you for considering contributing to the project! To contribute, please follow these guidelines:

1. Fork the repository and clone it to your local machine.

2. Create a new branch for your feature or bug fix:

   ```shell
   git checkout -b feature/your-feature-name
   ```

   Replace `your-feature-name` with a descriptive name for your contribution.

3. Make the necessary changes and ensure that your code follows the project's coding conventions and style guidelines - which currently are using PEP 8 for style and *black* for formatting 

4. Commit your changes with a clear and descriptive commit message:

   ```shell
   git commit -m "Add your commit message here"
   ```

5. Push your branch to your forked repository:

   ```shell
   git push origin feature/your-feature-name
   ```

6. Open a pull request from your forked repository to the main repository's `main` branch.

7. Provide a clear and detailed description of your changes in the pull request. Include any relevant information that would help reviewers understand your contribution.



## License
This project is licensed under the [MIT License](LICENSE).

## Contact
Feel free to reach out to me at @jspv on GitHub
