agent-framework-lib 0.1.0__tar.gz

agent_framework_lib-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,120 @@
+# Agent Framework Architecture
+
+## 1. Overview
+
+This document outlines the architecture of the Agent Framework, designed to provide a robust, scalable, and extensible platform for serving conversational agents.
+
+The primary architectural goal is the **Separation of Concerns**. Specifically, we aim to completely decouple the web server layer from the implementation details of any specific agent framework (e.g., Microsoft Autogen). The server should not know how an agent manages its internal memory or state; its only job is to handle web requests and interact with a generic `AgentInterface`.
+
+This design allows for easy extension to support other agent frameworks (like LangChain, etc.) in the future without modifying the core server logic.
+
+## 2. Core Components
+
+The architecture is composed of several key components, each with a single, well-defined responsibility.
+
+| Component                    | Responsibility                                                                                                                                                                                                                  |
+| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Server (FastAPI)**   | Handles HTTP requests, manages the web layer, and orchestrates high-level workflows by interacting with the `AgentManager`.                                                                                                   |
+| **AgentManager**       | The "wrapper" or provider. Manages the lifecycle of agents, including creation, state loading, and wrapping them in a proxy. It is the single point of contact for the server.                                                  |
+| **_ManagedAgentProxy** | An object that implements the `AgentInterface` and wraps the real agent. It transparently adds automatic state-saving behavior after a message is handled.                                                                    |
+| **RealAgent**          | The concrete agent implementation (e.g.,StreamingAutoGenAssistant). Implements the `AgentInterface` and contains the core conversational logic. It is responsible for its own state via `get_state()` and `load_state()`. |
+| **SessionStorage**     | The persistence layer. Manages the storage of two distinct data types: session metadata and agent state, linked by a `session_id`.                                                                                            |
+| **AutoGen State Mgr**  | A helper module used*only* by an Autogen-based `RealAgent` to handle the specifics of serializing, compressing, and managing Autogen's unique state format.                                                                 |
+
+## 3. Key Architectural Decisions & Principles
+
+### a. True Decoupling via an Agent Manager
+
+The server does not create agent instances or load their state directly. Instead, it delegates this entire responsibility to the `AgentManager`. This manager is the only component that understands how to assemble a fully functional agent, abstracting away all complexity from the server.
+
+### b. The Proxy Pattern for Transparent State Management
+
+A critical requirement was that state should be persisted automatically after an agent responds, without the server needing to explicitly trigger a "save" operation. We achieve this using the **Proxy Pattern**.
+
+- The `AgentManager` does not return the `RealAgent` to the server. It returns a `_ManagedAgentProxy` instead.
+- This proxy *looks and feels* exactly like a real agent because it implements the same `AgentInterface`.
+- When the server calls `handle_message()` on the proxy, the proxy first passes the call to the `RealAgent`.
+- Once the `RealAgent` returns a response, the proxy automatically calls the agent's `get_state()` method and instructs the `SessionStorage` to persist the new state.
+
+This makes state saving an invisible, automatic side-effect of handling a message, dramatically simplifying the server logic.
+
+### c. Separation of Agent State from Session Metadata
+
+Based on your insight, an agent's internal state (its memory, configuration, etc.) is a fundamentally different concern from the session's metadata (user ID, timestamps, correlation ID).
+
+This architecture formalizes that separation. The `SessionStorage` interface has distinct methods and underlying collections/tables for:
+
+1. `save_session()` / `load_session()`: For lightweight session metadata.
+2. `save_agent_state()` / `load_agent_state()`: For the potentially large and complex agent state "blob".
+
+This ensures the system is more organized, scalable, and easier to debug.
+
+### d. Interface-Driven Design for Extensibility
+
+The `AgentInterface` is the core contract that enables the entire system's flexibility. Any future agent, regardless of its underlying framework, can be integrated into the system by simply:
+
+1. Implementing the `AgentInterface`.
+2. Providing the logic for its own state management within the `get_state()` and `load_state()` methods.
+
+The server, `AgentManager`, and `SessionStorage` layers will require no changes.
+
+## 4. Workflows & Sequence Diagram
+
+The following diagram illustrates how the components interact across the main API workflows.
+
+```mermaid
+sequenceDiagram
+    participant User as User/Client
+    participant Server as Server (FastAPI)
+    participant AgentManager as AgentManager
+    participant _ManagedAgentProxy as AgentProxy
+    participant RealAgent as RealAgent
+    participant SessionStorage as SessionStorage
+    participant AutoGenStateManager as AutoGen State Mgr
+
+    Note over User, AutoGenStateManager: Workflow 1: Full Session (/init -> /message -> /end)
+
+    User->>+Server: POST /init (config)
+    Note over Server,AgentManager: Server creates AgentManager at startup. The manager has access to SessionStorage.
+    Server->>AgentManager: init_session(user_id, config)
+    AgentManager->>SessionStorage: save_session(session_metadata)
+    AgentManager->>SessionStorage: save_agent_state(session_id, empty_state)
+    Server-->>-User: 200 OK (session_id)
+
+    User->>+Server: POST /message (session_id, input)
+    Server->>AgentManager: get_agent(session_id, agent_class)
+    AgentManager->>SessionStorage: load_agent_state(session_id)
+    SessionStorage-->>AgentManager: returns stored_state
+    AgentManager->>RealAgent: new RealAgent()
+    AgentManager->>RealAgent: load_state(stored_state)
+    Note right of RealAgent: Agent uses its specific State Manager internally to decompress/load state.
+    RealAgent->>AutoGenStateManager: decompress_state(...)
+    AgentManager->>_ManagedAgentProxy: new _ManagedAgentProxy(real_agent)
+    Note over AgentManager,_ManagedAgentProxy: Proxy implements AgentInterface, hiding the real agent from the server.
+    AgentManager-->>Server: returns proxy_instance
+
+    Server->>_ManagedAgentProxy: handle_message(input)
+    _ManagedAgentProxy->>RealAgent: handle_message(input)
+    RealAgent-->>_ManagedAgentProxy: returns response
+    Note over _ManagedAgentProxy,RealAgent: Automatic State Persistence (Proxy Pattern)
+    _ManagedAgentProxy->>RealAgent: get_state()
+    RealAgent->>AutoGenStateManager: compress_state(...)
+    RealAgent-->>_ManagedAgentProxy: returns new_state
+    _ManagedAgentProxy->>SessionStorage: save_agent_state(session_id, new_state)
+    _ManagedAgentProxy-->>Server: returns response
+    Server-->>-User: 200 OK (response)
+
+    User->>+Server: POST /end (session_id)
+    Server->>AgentManager: end_session(session_id)
+    AgentManager->>SessionStorage: update_session_status('closed')
+    Server-->>-User: 200 OK
+
+    Note over User, AutoGenStateManager: Workflow 2: Stateless Endpoints (e.g., /metadata)
+
+    User->>+Server: GET /metadata
+    Note over Server,RealAgent: This flow is stateless and doesn't need the AgentManager or persistence.
+    Server->>RealAgent: new RealAgent() (temporary instance)
+    Server->>RealAgent: get_metadata()
+    RealAgent-->>Server: returns metadata
+    Server-->>-User: 200 OK (metadata)
+```

agent_framework_lib-0.1.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to the Agent Framework will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-01-XX
+
+### Added
+- Initial release of Agent Framework
+- **Core Framework Features:**
+  - Abstract `AgentInterface` for building custom agents
+  - FastAPI-based server with automatic session management
+  - Multi-provider AI model support (OpenAI, Gemini)
+  - Automatic model routing and configuration
+  - Session-based conversation handling with persistence
+  - Streaming response support
+  - Multi-modal input support (text, images, files)
+
+- **Session Management:**
+  - Memory-based and MongoDB session storage backends  
+  - Automatic agent state persistence using proxy pattern
+  - Session workflow with init/end endpoints
+  - Correlation ID support for linking sessions across agents
+  - Session metadata and configuration management
+
+- **Agent Features:**
+  - AutoGen-based base agent implementation
+  - System prompt configuration and templating
+  - Dynamic agent configuration (temperature, tokens, etc.)
+  - Media detection in agent responses
+  - Multi-agent conversation support
+  - MCP (Model Context Protocol) integration
+
+- **Authentication & Security:**
+  - Basic authentication support
+  - API key authentication
+  - Configurable authentication requirements
+
+- **User Experience:**
+  - Built-in web test interface (`/testapp`)
+  - User feedback system (thumbs up/down, session flags)
+  - Comprehensive API documentation
+  - Response time tracking and analytics
+  - Real-time streaming endpoints
+
+- **Library Usage:**
+  - Convenience function `create_basic_agent_server()` for easy setup
+  - Pip installable from GitHub repositories
+  - Extensive examples and documentation
+
+- **Developer Tools:**
+  - Comprehensive test suite with fixtures
+  - Debug logging with configurable levels
+  - Model configuration validation endpoints
+  - MongoDB integration with automatic indexing
+  - Docker support and examples
+
+### Dependencies
+- fastapi>=0.115.12
+- autogen-agentchat>=0.6.3
+- autogen-core>=0.6.3
+- autogen-ext[mcp,openai]>=0.6.3
+- uvicorn>=0.34.2
+- pymongo>=4.10.1
+- motor>=3.6.0
+- And other supporting libraries
+
+### Requirements
+- Python 3.10 or higher
+- Optional: MongoDB for persistent session storage
+- API keys for OpenAI and/or Gemini models
+
+[Unreleased]: https://github.com/Cinco-AI/AgentFramework/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Cinco-AI/AgentFramework/releases/tag/v0.1.0 

agent_framework_lib-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Agent Framework Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

agent_framework_lib-0.1.0/MANIFEST.in

@@ -0,0 +1,63 @@
+# Include essential documentation and configuration files
+include README.md
+include CHANGELOG.md
+include LICENSE
+include pyproject.toml
+
+# Include architecture documentation
+include ARCHITECTURE.md
+
+# Include HTML templates and static files from the main package
+include agent_framework/test_app.html
+include agent_framework/*.html
+include agent_framework/*.json
+include agent_framework/*.yaml
+include agent_framework/*.yml
+include agent_framework/*.css
+include agent_framework/*.js
+
+# Include specific example files but exclude large dependencies
+include examples/*.py
+include examples/*.md
+include examples/*.txt
+include examples/*.toml
+include examples/*.env
+include examples/requirements.txt
+include examples/pyproject.toml
+recursive-include examples/dependencies *.yaml
+recursive-include examples/dependencies *.yml
+
+# Exclude development and cache files
+exclude .gitignore
+exclude *.code-workspace
+exclude package-lock.json
+exclude uv.lock
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * *.pyo
+recursive-exclude * .DS_Store
+
+# Exclude entire directories
+recursive-exclude .git *
+recursive-exclude .vscode *
+recursive-exclude .cursor *
+recursive-exclude .pytest_cache *
+recursive-exclude specs *
+recursive-exclude .venv *
+recursive-exclude mcp-server *
+recursive-exclude tests *
+
+# CRITICAL: Exclude heavy node_modules and similar directories
+recursive-exclude examples/node_modules *
+recursive-exclude node_modules *
+recursive-exclude */node_modules *
+
+# Exclude other development directories
+prune .git
+prune .vscode 
+prune .cursor
+prune specs
+prune .venv
+prune node_modules
+prune mcp-server
+prune examples/node_modules