phx-ashborn 0.1.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. phx_ashborn-0.1.3/PKG-INFO +293 -0
  2. phx_ashborn-0.1.3/README.md +257 -0
  3. phx_ashborn-0.1.3/phoenix/__init__.py +27 -0
  4. phx_ashborn-0.1.3/phoenix/agent/__init__.py +7 -0
  5. phx_ashborn-0.1.3/phoenix/agent/agent.py +81 -0
  6. phx_ashborn-0.1.3/phoenix/agent/loop.py +77 -0
  7. phx_ashborn-0.1.3/phoenix/audio/__init__.py +5 -0
  8. phx_ashborn-0.1.3/phoenix/audio/base.py +12 -0
  9. phx_ashborn-0.1.3/phoenix/audio/local.py +46 -0
  10. phx_ashborn-0.1.3/phoenix/audio/openai.py +63 -0
  11. phx_ashborn-0.1.3/phoenix/cache/__init__.py +4 -0
  12. phx_ashborn-0.1.3/phoenix/cache/base.py +12 -0
  13. phx_ashborn-0.1.3/phoenix/cache/redis_cache.py +37 -0
  14. phx_ashborn-0.1.3/phoenix/cognition/__init__.py +9 -0
  15. phx_ashborn-0.1.3/phoenix/cognition/analyzer.py +60 -0
  16. phx_ashborn-0.1.3/phoenix/cognition/planner.py +53 -0
  17. phx_ashborn-0.1.3/phoenix/cognition/reflector.py +39 -0
  18. phx_ashborn-0.1.3/phoenix/cognition/thinker.py +30 -0
  19. phx_ashborn-0.1.3/phoenix/core/__init__.py +1 -0
  20. phx_ashborn-0.1.3/phoenix/core/base.py +3 -0
  21. phx_ashborn-0.1.3/phoenix/core/config.py +69 -0
  22. phx_ashborn-0.1.3/phoenix/core/container.py +15 -0
  23. phx_ashborn-0.1.3/phoenix/core/exceptions.py +11 -0
  24. phx_ashborn-0.1.3/phoenix/core/hardware_check.py +110 -0
  25. phx_ashborn-0.1.3/phoenix/core/lifecycle.py +52 -0
  26. phx_ashborn-0.1.3/phoenix/core/utils.py +38 -0
  27. phx_ashborn-0.1.3/phoenix/db/__init__.py +4 -0
  28. phx_ashborn-0.1.3/phoenix/db/base.py +12 -0
  29. phx_ashborn-0.1.3/phoenix/db/sqlalchemy.py +20 -0
  30. phx_ashborn-0.1.3/phoenix/execution/__init__.py +7 -0
  31. phx_ashborn-0.1.3/phoenix/execution/actor.py +38 -0
  32. phx_ashborn-0.1.3/phoenix/execution/tool_manager.py +19 -0
  33. phx_ashborn-0.1.3/phoenix/framework/chatbot.py +226 -0
  34. phx_ashborn-0.1.3/phoenix/framework/security.py +101 -0
  35. phx_ashborn-0.1.3/phoenix/insight/__init__.py +13 -0
  36. phx_ashborn-0.1.3/phoenix/insight/base.py +7 -0
  37. phx_ashborn-0.1.3/phoenix/insight/composer.py +27 -0
  38. phx_ashborn-0.1.3/phoenix/insight/engine.py +120 -0
  39. phx_ashborn-0.1.3/phoenix/insight/optimizer.py +138 -0
  40. phx_ashborn-0.1.3/phoenix/insight/retriever.py +26 -0
  41. phx_ashborn-0.1.3/phoenix/insight/vlm_pipeline.py +142 -0
  42. phx_ashborn-0.1.3/phoenix/llm/__init__.py +7 -0
  43. phx_ashborn-0.1.3/phoenix/llm/base.py +22 -0
  44. phx_ashborn-0.1.3/phoenix/llm/local.py +179 -0
  45. phx_ashborn-0.1.3/phoenix/llm/openai.py +110 -0
  46. phx_ashborn-0.1.3/phoenix/llm/vlm_local.py +288 -0
  47. phx_ashborn-0.1.3/phoenix/llm/vlm_openai.py +110 -0
  48. phx_ashborn-0.1.3/phoenix/main.py +266 -0
  49. phx_ashborn-0.1.3/phoenix/memory/__init__.py +6 -0
  50. phx_ashborn-0.1.3/phoenix/memory/base.py +27 -0
  51. phx_ashborn-0.1.3/phoenix/memory/history.py +44 -0
  52. phx_ashborn-0.1.3/phoenix/memory/hybrid.py +72 -0
  53. phx_ashborn-0.1.3/phoenix/memory/long_term.py +38 -0
  54. phx_ashborn-0.1.3/phoenix/memory/manager.py +52 -0
  55. phx_ashborn-0.1.3/phoenix/memory/reflection.py +35 -0
  56. phx_ashborn-0.1.3/phoenix/memory/semantic.py +52 -0
  57. phx_ashborn-0.1.3/phoenix/memory/session.py +18 -0
  58. phx_ashborn-0.1.3/phoenix/memory/short_term.py +18 -0
  59. phx_ashborn-0.1.3/phoenix/observability/__init__.py +4 -0
  60. phx_ashborn-0.1.3/phoenix/observability/logger.py +30 -0
  61. phx_ashborn-0.1.3/phoenix/observability/tracing.py +46 -0
  62. phx_ashborn-0.1.3/phoenix/queue/__init__.py +4 -0
  63. phx_ashborn-0.1.3/phoenix/queue/base.py +6 -0
  64. phx_ashborn-0.1.3/phoenix/queue/celery_queue.py +16 -0
  65. phx_ashborn-0.1.3/phoenix/rag/__init__.py +3 -0
  66. phx_ashborn-0.1.3/phoenix/rag/pipeline.py +391 -0
  67. phx_ashborn-0.1.3/phoenix/tools/__init__.py +17 -0
  68. phx_ashborn-0.1.3/phoenix/tools/base.py +44 -0
  69. phx_ashborn-0.1.3/phoenix/tools/code.py +101 -0
  70. phx_ashborn-0.1.3/phoenix/tools/io.py +78 -0
  71. phx_ashborn-0.1.3/phoenix/tools/patch.py +58 -0
  72. phx_ashborn-0.1.3/phoenix/tools/registry.py +33 -0
  73. phx_ashborn-0.1.3/phoenix/tools/search.py +30 -0
  74. phx_ashborn-0.1.3/phoenix/training/base.py +29 -0
  75. phx_ashborn-0.1.3/phoenix/training/local_finetuner.py +141 -0
  76. phx_ashborn-0.1.3/phoenix/training/openai_finetuner.py +77 -0
  77. phx_ashborn-0.1.3/phoenix/vector/__init__.py +4 -0
  78. phx_ashborn-0.1.3/phoenix/vector/base.py +22 -0
  79. phx_ashborn-0.1.3/phoenix/vector/chroma.py +108 -0
  80. phx_ashborn-0.1.3/phoenix/vector/embeddings.py +52 -0
  81. phx_ashborn-0.1.3/phoenix/vector/qdrant.py +21 -0
  82. phx_ashborn-0.1.3/phx_ashborn.egg-info/PKG-INFO +293 -0
  83. phx_ashborn-0.1.3/phx_ashborn.egg-info/SOURCES.txt +88 -0
  84. phx_ashborn-0.1.3/phx_ashborn.egg-info/dependency_links.txt +1 -0
  85. phx_ashborn-0.1.3/phx_ashborn.egg-info/requires.txt +27 -0
  86. phx_ashborn-0.1.3/phx_ashborn.egg-info/top_level.txt +1 -0
  87. phx_ashborn-0.1.3/pyproject.toml +44 -0
  88. phx_ashborn-0.1.3/setup.cfg +4 -0
  89. phx_ashborn-0.1.3/setup.py +43 -0
  90. phx_ashborn-0.1.3/tests/test_agent.py +55 -0
@@ -0,0 +1,293 @@
1
+ Metadata-Version: 2.4
2
+ Name: phx-ashborn
3
+ Version: 0.1.3
4
+ Summary: Advanced AI Infrastructure SDK for Agentic Applications
5
+ Author: blackeagle686
6
+ Requires-Python: >=3.9
7
+ Description-Content-Type: text/markdown
8
+ Requires-Dist: python-dotenv>=1.0.0
9
+ Requires-Dist: requests>=2.28.0
10
+ Requires-Dist: openai>=1.0.0
11
+ Requires-Dist: markdown>=3.4.0
12
+ Requires-Dist: beautifulsoup4>=4.11.0
13
+ Requires-Dist: chromadb>=0.4.0
14
+ Requires-Dist: sentence-transformers>=2.2.0
15
+ Requires-Dist: pypdf>=3.10.0
16
+ Requires-Dist: python-docx>=0.8.11
17
+ Requires-Dist: qdrant-client>=1.6.0
18
+ Requires-Dist: redis>=4.5.0
19
+ Requires-Dist: celery>=5.3.0
20
+ Requires-Dist: sqlalchemy>=2.0.0
21
+ Requires-Dist: django>=5.0.0
22
+ Requires-Dist: pandas
23
+ Requires-Dist: openpyxl
24
+ Requires-Dist: gTTS
25
+ Requires-Dist: SpeechRecognition
26
+ Requires-Dist: pydub
27
+ Requires-Dist: Pillow
28
+ Requires-Dist: psutil
29
+ Provides-Extra: full
30
+ Requires-Dist: torch; extra == "full"
31
+ Requires-Dist: transformers; extra == "full"
32
+ Requires-Dist: accelerate; extra == "full"
33
+ Requires-Dist: bitsandbytes; extra == "full"
34
+ Dynamic: author
35
+ Dynamic: requires-python
36
+
37
+ # 🐦‍🔥 Phoenix AI (Advanced AI Infrastructure SDK)
38
+
39
+ <p align="center">
40
+ <img src="https://raw.githubusercontent.com/blackeagle686/phoenix-ai/master/docs/statics/images/phx-light-circle.png" alt="Phoenix AI Logo" width="500">
41
+ </p>
42
+
43
+ A production-ready, modular backend infrastructure SDK designed for AI-powered Python backend services.
44
+
45
+ Whether you are building with FastAPI, Django, or a custom event-driven service, **Phoenix AI** eliminates repetitive backend setup.
46
+
47
+ ## 🐦‍🔥 Key Requirements & Core Features
48
+
49
+ 1. **Dependency Injection**: Central standard registry. No manual instantiation inside business logic.
50
+ 2. **Interface First**: Every module complies with an asynchronous base contract (`BaseCache`, `BaseLLM`, `BaseVectorDB`, etc.).
51
+ 3. **Flexible Vector DB**: Native support for **ChromaDB** (Default/Persistent) and **Qdrant**.
52
+ 4. **Embedded Insights**: Pre-configured with `sentence-transformers` (`all-MiniLM-L6-v2`) for local embedding generation.
53
+ 5. **RAG Orchestration**: All-in-one `RAGPipeline` that handles document loading (.pdf, .docx, .xlsx), SQL databases, external APIs, and web scraping.
54
+
55
+ ## 📦 Installation
56
+ Choose the method that fits your workflow best.
57
+
58
+ ### 1. Automated Installation (Recommended)
59
+ Get everything ready in one command (handles Python deps and Redis setup):
60
+ ```bash
61
+ # For Linux/macOS/WSL
62
+ chmod +x install.sh
63
+ ./install.sh
64
+
65
+ # For Windows
66
+ install.bat
67
+ ```
68
+
69
+ ### 2. Manual Installation
70
+ Alternatively, use the provided `Makefile` or `pip`:
71
+ ```bash
72
+ # Full installation with all services (VDB, RAG, Memory, etc.)
73
+ make install-full
74
+
75
+ # Or basic installation
76
+ make install
77
+ ```
78
+
79
+ ### 3. Pip Installation (Official)
80
+ ```bash
81
+ pip install phx-ashborn
82
+
83
+ # Or with full local model support
84
+ pip install "phx-ashborn[full]"
85
+ ```
86
+ 3. **Configure Environment Variables**:
87
+ Copy the provided template and add your keys:
88
+ ```bash
89
+ cp .env.example .env
90
+ ```
91
+ Edit `.env` with your settings:
92
+ ```env
93
+ OPENAI_API_KEY="your_key"
94
+ REDIS_URL="redis://localhost:6379/0"
95
+ # See .env.example for more advanced options
96
+ ```
97
+
98
+ ### 🛠️ System Dependencies
99
+ - **Redis Server**: Required for stateful memory and caching.
100
+ - Ubuntu: `sudo apt install redis-server`
101
+ - macOS: `brew install redis`
102
+
103
+ ## 🐦‍🔥 Framework Mode: High-Level ChatBot
104
+
105
+ The Phoenix AI SDK now includes a high-level **Framework Layer** that allows you to build complex AI agents with Vision, Speech, RAG, and Memory in just **one line of code**.
106
+
107
+ ```python
108
+ from phoenix import ChatBot
109
+
110
+ # Build the complete AI Agent with Security and Custom Config
111
+ bot = (ChatBot(local=True, vlm=True)
112
+ .with_rag(["./docs", "./src"]) # Folders or files
113
+ .with_memory() # Enable session memory
114
+ .with_security(mode="strict") # Protection against Prompt Injection
115
+ .with_system_prompt("Expert Dev") # Guide bot behavior
116
+ .build())
117
+
118
+ # Or switch to OpenAI with one line
119
+ # bot.with_openai(api_key="sk-...", base_url="https://api.openai.com")
120
+
121
+ # Multi-modal interaction
122
+ response = await bot.chat("What's in this image?", image_path="vision.jpg")
123
+ print(response)
124
+ ```
125
+ > [!TIP]
126
+ > Use `.set_session("user_123")` on the bot instance to switch between different users in production environments like FastAPI.
127
+
128
+ ## 🐦‍🔥 Framework Mode: Autonomous Agent
129
+
130
+ The Phoenix AI SDK now supports creating a fully autonomous agent that can think, analyze, plan, execute tools, and reflect on its progress with a single line of code!
131
+
132
+ > [!TIP]
133
+ > For a deep dive into the architecture and integration patterns, check out the **[Agent Framework Guide](https://github.com/blackeagle686/phoenix-ai/blob/master/docs/AGENT_GUIDE.md)**, **[Django Integration Guide](https://github.com/blackeagle686/phoenix-ai/blob/master/docs/DJANGO_INTEGRATION.md)**, **[GUI Integration Guide](https://github.com/blackeagle686/phoenix-ai/blob/master/docs/GUI_INTEGRATION.md)**, or the **[API Integration Guide](https://github.com/blackeagle686/phoenix-ai/blob/master/docs/API_INTEGRATION.md)**.
134
+
135
+ #### ⚡ High-Speed Cognitive Engine
136
+ * **Parallel Awareness**: The `Thinker` and `Analyzer` run concurrently, allowing the agent to understand both your prompt and your project structure in a single cognitive step.
137
+ * **Multi-Action Planning**: The agent can plan and execute multiple independent actions (tools) in parallel, cutting task completion time by up to 60%.
138
+ * **Concurrent Memory**: Reflection, consolidation, and logging happen in the background, ensuring zero-latency transitions between agent steps.
139
+ * **Hybrid Memory Layer**: Integrated `ShortTerm`, `LongTerm` (Vector), `Session`, and `Reflection` memories with parallel retrieval support.
140
+
141
+ ```python
142
+ import asyncio
143
+ from phoenix.agent import Agent
144
+ from phoenix.llm.openai import OpenAILLM
145
+ from phoenix.memory.hybrid import HybridMemory
146
+ from phoenix.tools.registry import ToolRegistry
147
+
148
+ async def agent_demo():
149
+ # Initialize the high-speed Agent
150
+ agent = Agent() # Uses default OpenAILLM, HybridMemory, and Parallel Tools
151
+
152
+ # Run a complex engineering task
153
+ # The agent will automatically:
154
+ # 1. Think: Deconstruct the prompt
155
+ # 2. Analyze: Scan the repo structure and tech stack
156
+ # 3. Plan: Create parallel steps for search and code analysis
157
+ # 4. Act: Execute tools concurrently (e.g. searching while analyzing code)
158
+ # 5. Reflect: Verify the fix and learn from the process
159
+
160
+ prompt = "Find the redundant code in the memory module and optimize it using the new parallel patterns."
161
+ result = await agent.run(prompt, mode="plan")
162
+
163
+ print(f"Agent Engineering Report: {result}")
164
+ ```
165
+
166
+ ### 🐦‍🔥 Custom Tools & Engineering Suite
167
+
168
+ The Agent comes pre-configured with a suite of engineering-grade tools:
169
+ * **`python_analyzer`**: (High-Speed) AST-based indexing of classes and functions for precise code navigation.
170
+ * **`file_update_multi`**: (Atomic) Applies multiple code changes across different parts of a file in one go.
171
+ * **`python_repl`**: Executes Python logic in a sandbox.
172
+ * **`web_search`**: Live internet access for news and documentation.
173
+ * **`file_read / file_write / file_search`**: Advanced filesystem operations.
174
+
175
+ You can also easily create and inject your own custom tools using the `@tool` decorator:
176
+
177
+ ```python
178
+ from phoenix.tools import tool
179
+
180
+ # 1. Define your custom logic
181
+ @tool(name="custom_math", description="Calculates the square of a given number. Input: 'number' (int).")
182
+ def custom_math_tool(number: int):
183
+ return f"The square of {number} is {number ** 2}"
184
+
185
+ # 2. Register it directly to the agent
186
+ agent.register_tool(custom_math_tool)
187
+
188
+ # 3. The agent can now autonomously use 'custom_math' in its planning!
189
+ await agent.run("What is the square of 12?")
190
+ ```
191
+
192
+ ### ⚡ Execution Modes (Auto-Routing)
193
+
194
+ The Agent features intelligent routing to save time and API costs on simple tasks. By default, it runs in `mode="auto"`.
195
+ - **`auto`**: The agent analyzes the prompt. If it's a simple question, it gives a direct answer. If it requires tools or multi-step logic, it spins up the planning loop.
196
+ - **`fast_ans`**: Forces the agent to skip planning and answer immediately using memory context.
197
+ - **`plan`**: Forces the agent into the rigorous `Think -> Plan -> Act -> Reflect` loop.
198
+
199
+ ```python
200
+ # Forces a fast answer (Bypasses tool execution)
201
+ await agent.run("Hi, who are you?", mode="fast_ans")
202
+
203
+ # Forces complex planning
204
+ await agent.run("Search the web for the latest Python release...", mode="plan")
205
+ ```
206
+
207
+ ## 📖 Quickstart: RAG Pipeline
208
+
209
+ The `RAGPipeline` is the highest-level service for handling document-based knowledge.
210
+
211
+ ```python
212
+ import asyncio
213
+ from phoenix import init_phoenix, startup_phoenix, get_rag_pipeline
214
+
215
+ async def rag_demo():
216
+ init_phoenix()
217
+ await startup_phoenix()
218
+ rag = get_rag_pipeline()
219
+
220
+ # 1. Ingest documents (Supports Docs + Source Code .py, .js, .go, .rs, etc.)
221
+ await rag.ingest("./my_project")
222
+
223
+ # 2. Ingest from GitHub Repository (Automated cloning & indexing)
224
+ await rag.ingest_github("https://github.com/blackeagle686/phoenix-ai.git")
225
+
226
+ # 3. Ingest from Web URL
227
+ await rag.ingest_url("https://example.com/docs/api")
228
+
229
+ # 4. Query with automatic Citations
230
+ answer = await rag.query("How do I extend the cache layer?")
231
+ print(f"AI Answer: {answer}")
232
+ ```
233
+
234
+ ### 🐦‍🔥 Source Attribution
235
+ The SDK now automatically instructs the LLM to cite its sources. When you query the RAG pipeline, the response will often include markers like `[Source: cloud.pdf]` or `[Source: https://example.com]`.
236
+
237
+ ## ⚠️ Local Model Hardware Requirements
238
+ If you plan to use local inference (Ollama or Transformers), please ensure your system meets these specifications:
239
+ - **RAM**: 8GB Minimum (16GB+ recommended).
240
+ - **GPU**: 4GB+ VRAM required for VLM models (using 4-bit quantization).
241
+ - **Disk**: 10GB+ free space for model storage.
242
+
243
+ > [!WARNING]
244
+ > High-resource models may cause system instability on low-RAM or CPU-only devices. The SDK defaults to a safety-first approach and will prompt for confirmation before starting local providers.
245
+
246
+ ## 🐦‍🔥 Dynamic Fallbacks & Native PyTorch
247
+
248
+ phoenix includes a robust "fail-loud and recover gracefully" orchestration architecture for AI providers:
249
+
250
+ ### 1. Interactive Provider Fallbacks
251
+ If your primary provider (e.g. Local) fails to connect or crashes, the SDK's orchestration (`VLMPipeline` / `InsightEngine`) instantly intercepts the failure and prompts you to fallback to the secondary provider (e.g. OpenAI), bypassing pipeline crashes.
252
+
253
+ ### 2. Native PyTorch Singleton Caching (`LocalVLM` & `LocalLLM`)
254
+ No `Ollama` server? No problem! The local providers automatically detect if Hugging Face `transformers` is installed and spin up models natively in your local GPU using an optimized Singleton cache.
255
+ > **Jupyter/Colab Tip**: If you face persistent `Ollama` warnings after installing `transformers`, run `LocalVLM._model_cache.clear()` or `LocalLLM._model_cache.clear()` in your notebook to wipe the previous state and force a PyTorch native reload.
256
+
257
+ ### 3. Automatic 4-Bit Quantization
258
+ To prevent `CUDA Out of Memory` (OOM) errors on smaller GPUs (like Colab T4s), the SDK auto-detects `bitsandbytes` (`pip install bitsandbytes`) and instantly applies `load_in_4bit=True` to shrink massive models (like Qwen2-VL) into your VRAM.
259
+
260
+ ### 4. Resilient RAG PDFs
261
+ The `RAGPipeline.ingest()` method supports PDFs robustly by sequentially testing for parsing libraries: `pypdf`, `pymupdf` (`fitz`), `pdfplumber`, and `PyPDF2`. Simply install whichever you prefer (`pip install pymupdf` is recommended for speed) and it works flawlessly!
262
+
263
+ ## 🐦‍🔥 Advanced Usage: Insight Engine
264
+
265
+ The `InsightEngine` performs full context retrieval, query rewriting, and LLM generation efficiently.
266
+
267
+ ```python
268
+ from phoenix import init_phoenix, get_insight_engine
269
+
270
+ async def insight_demo():
271
+ init_phoenix()
272
+ insight = get_insight_engine()
273
+
274
+ # This invokes: Clean Query -> Vector Search -> Rerank -> LLM Generation
275
+ final_response = await insight.query("How do I extend the cache layer?")
276
+ print(final_response)
277
+ ```
278
+
279
+ ## 🖼️ Quickstart: VLM (Vision)
280
+
281
+ The `VLMPipeline` orchestrates vision tasks with automatic caching and RAG.
282
+
283
+ ```python
284
+ from phoenix import init_phoenix_full, get_vlm_pipeline
285
+
286
+ async def vision_demo():
287
+ await init_phoenix_full()
288
+ vlm = get_vlm_pipeline()
289
+
290
+ # Integrated: Result Caching + RAG context injection
291
+ answer = await vlm.ask("What is in this image?", "image.png", use_rag=True)
292
+ print(answer)
293
+ ```
@@ -0,0 +1,257 @@
1
+ # 🐦‍🔥 Phoenix AI (Advanced AI Infrastructure SDK)
2
+
3
+ <p align="center">
4
+ <img src="https://raw.githubusercontent.com/blackeagle686/phoenix-ai/master/docs/statics/images/phx-light-circle.png" alt="Phoenix AI Logo" width="500">
5
+ </p>
6
+
7
+ A production-ready, modular backend infrastructure SDK designed for AI-powered Python backend services.
8
+
9
+ Whether you are building with FastAPI, Django, or a custom event-driven service, **Phoenix AI** eliminates repetitive backend setup.
10
+
11
+ ## 🐦‍🔥 Key Requirements & Core Features
12
+
13
+ 1. **Dependency Injection**: Central standard registry. No manual instantiation inside business logic.
14
+ 2. **Interface First**: Every module complies with an asynchronous base contract (`BaseCache`, `BaseLLM`, `BaseVectorDB`, etc.).
15
+ 3. **Flexible Vector DB**: Native support for **ChromaDB** (Default/Persistent) and **Qdrant**.
16
+ 4. **Embedded Insights**: Pre-configured with `sentence-transformers` (`all-MiniLM-L6-v2`) for local embedding generation.
17
+ 5. **RAG Orchestration**: All-in-one `RAGPipeline` that handles document loading (.pdf, .docx, .xlsx), SQL databases, external APIs, and web scraping.
18
+
19
+ ## 📦 Installation
20
+ Choose the method that fits your workflow best.
21
+
22
+ ### 1. Automated Installation (Recommended)
23
+ Get everything ready in one command (handles Python deps and Redis setup):
24
+ ```bash
25
+ # For Linux/macOS/WSL
26
+ chmod +x install.sh
27
+ ./install.sh
28
+
29
+ # For Windows
30
+ install.bat
31
+ ```
32
+
33
+ ### 2. Manual Installation
34
+ Alternatively, use the provided `Makefile` or `pip`:
35
+ ```bash
36
+ # Full installation with all services (VDB, RAG, Memory, etc.)
37
+ make install-full
38
+
39
+ # Or basic installation
40
+ make install
41
+ ```
42
+
43
+ ### 3. Pip Installation (Official)
44
+ ```bash
45
+ pip install phx-ashborn
46
+
47
+ # Or with full local model support
48
+ pip install "phx-ashborn[full]"
49
+ ```
50
+ 3. **Configure Environment Variables**:
51
+ Copy the provided template and add your keys:
52
+ ```bash
53
+ cp .env.example .env
54
+ ```
55
+ Edit `.env` with your settings:
56
+ ```env
57
+ OPENAI_API_KEY="your_key"
58
+ REDIS_URL="redis://localhost:6379/0"
59
+ # See .env.example for more advanced options
60
+ ```
61
+
62
+ ### 🛠️ System Dependencies
63
+ - **Redis Server**: Required for stateful memory and caching.
64
+ - Ubuntu: `sudo apt install redis-server`
65
+ - macOS: `brew install redis`
66
+
67
+ ## 🐦‍🔥 Framework Mode: High-Level ChatBot
68
+
69
+ The Phoenix AI SDK now includes a high-level **Framework Layer** that allows you to build complex AI agents with Vision, Speech, RAG, and Memory in just **one line of code**.
70
+
71
+ ```python
72
+ from phoenix import ChatBot
73
+
74
+ # Build the complete AI Agent with Security and Custom Config
75
+ bot = (ChatBot(local=True, vlm=True)
76
+ .with_rag(["./docs", "./src"]) # Folders or files
77
+ .with_memory() # Enable session memory
78
+ .with_security(mode="strict") # Protection against Prompt Injection
79
+ .with_system_prompt("Expert Dev") # Guide bot behavior
80
+ .build())
81
+
82
+ # Or switch to OpenAI with one line
83
+ # bot.with_openai(api_key="sk-...", base_url="https://api.openai.com")
84
+
85
+ # Multi-modal interaction
86
+ response = await bot.chat("What's in this image?", image_path="vision.jpg")
87
+ print(response)
88
+ ```
89
+ > [!TIP]
90
+ > Use `.set_session("user_123")` on the bot instance to switch between different users in production environments like FastAPI.
91
+
92
+ ## 🐦‍🔥 Framework Mode: Autonomous Agent
93
+
94
+ The Phoenix AI SDK now supports creating a fully autonomous agent that can think, analyze, plan, execute tools, and reflect on its progress with a single line of code!
95
+
96
+ > [!TIP]
97
+ > For a deep dive into the architecture and integration patterns, check out the **[Agent Framework Guide](https://github.com/blackeagle686/phoenix-ai/blob/master/docs/AGENT_GUIDE.md)**, **[Django Integration Guide](https://github.com/blackeagle686/phoenix-ai/blob/master/docs/DJANGO_INTEGRATION.md)**, **[GUI Integration Guide](https://github.com/blackeagle686/phoenix-ai/blob/master/docs/GUI_INTEGRATION.md)**, or the **[API Integration Guide](https://github.com/blackeagle686/phoenix-ai/blob/master/docs/API_INTEGRATION.md)**.
98
+
99
+ #### ⚡ High-Speed Cognitive Engine
100
+ * **Parallel Awareness**: The `Thinker` and `Analyzer` run concurrently, allowing the agent to understand both your prompt and your project structure in a single cognitive step.
101
+ * **Multi-Action Planning**: The agent can plan and execute multiple independent actions (tools) in parallel, cutting task completion time by up to 60%.
102
+ * **Concurrent Memory**: Reflection, consolidation, and logging happen in the background, ensuring zero-latency transitions between agent steps.
103
+ * **Hybrid Memory Layer**: Integrated `ShortTerm`, `LongTerm` (Vector), `Session`, and `Reflection` memories with parallel retrieval support.
104
+
105
+ ```python
106
+ import asyncio
107
+ from phoenix.agent import Agent
108
+ from phoenix.llm.openai import OpenAILLM
109
+ from phoenix.memory.hybrid import HybridMemory
110
+ from phoenix.tools.registry import ToolRegistry
111
+
112
+ async def agent_demo():
113
+ # Initialize the high-speed Agent
114
+ agent = Agent() # Uses default OpenAILLM, HybridMemory, and Parallel Tools
115
+
116
+ # Run a complex engineering task
117
+ # The agent will automatically:
118
+ # 1. Think: Deconstruct the prompt
119
+ # 2. Analyze: Scan the repo structure and tech stack
120
+ # 3. Plan: Create parallel steps for search and code analysis
121
+ # 4. Act: Execute tools concurrently (e.g. searching while analyzing code)
122
+ # 5. Reflect: Verify the fix and learn from the process
123
+
124
+ prompt = "Find the redundant code in the memory module and optimize it using the new parallel patterns."
125
+ result = await agent.run(prompt, mode="plan")
126
+
127
+ print(f"Agent Engineering Report: {result}")
128
+ ```
129
+
130
+ ### 🐦‍🔥 Custom Tools & Engineering Suite
131
+
132
+ The Agent comes pre-configured with a suite of engineering-grade tools:
133
+ * **`python_analyzer`**: (High-Speed) AST-based indexing of classes and functions for precise code navigation.
134
+ * **`file_update_multi`**: (Atomic) Applies multiple code changes across different parts of a file in one go.
135
+ * **`python_repl`**: Executes Python logic in a sandbox.
136
+ * **`web_search`**: Live internet access for news and documentation.
137
+ * **`file_read / file_write / file_search`**: Advanced filesystem operations.
138
+
139
+ You can also easily create and inject your own custom tools using the `@tool` decorator:
140
+
141
+ ```python
142
+ from phoenix.tools import tool
143
+
144
+ # 1. Define your custom logic
145
+ @tool(name="custom_math", description="Calculates the square of a given number. Input: 'number' (int).")
146
+ def custom_math_tool(number: int):
147
+ return f"The square of {number} is {number ** 2}"
148
+
149
+ # 2. Register it directly to the agent
150
+ agent.register_tool(custom_math_tool)
151
+
152
+ # 3. The agent can now autonomously use 'custom_math' in its planning!
153
+ await agent.run("What is the square of 12?")
154
+ ```
155
+
156
+ ### ⚡ Execution Modes (Auto-Routing)
157
+
158
+ The Agent features intelligent routing to save time and API costs on simple tasks. By default, it runs in `mode="auto"`.
159
+ - **`auto`**: The agent analyzes the prompt. If it's a simple question, it gives a direct answer. If it requires tools or multi-step logic, it spins up the planning loop.
160
+ - **`fast_ans`**: Forces the agent to skip planning and answer immediately using memory context.
161
+ - **`plan`**: Forces the agent into the rigorous `Think -> Plan -> Act -> Reflect` loop.
162
+
163
+ ```python
164
+ # Forces a fast answer (Bypasses tool execution)
165
+ await agent.run("Hi, who are you?", mode="fast_ans")
166
+
167
+ # Forces complex planning
168
+ await agent.run("Search the web for the latest Python release...", mode="plan")
169
+ ```
170
+
171
+ ## 📖 Quickstart: RAG Pipeline
172
+
173
+ The `RAGPipeline` is the highest-level service for handling document-based knowledge.
174
+
175
+ ```python
176
+ import asyncio
177
+ from phoenix import init_phoenix, startup_phoenix, get_rag_pipeline
178
+
179
+ async def rag_demo():
180
+ init_phoenix()
181
+ await startup_phoenix()
182
+ rag = get_rag_pipeline()
183
+
184
+ # 1. Ingest documents (Supports Docs + Source Code .py, .js, .go, .rs, etc.)
185
+ await rag.ingest("./my_project")
186
+
187
+ # 2. Ingest from GitHub Repository (Automated cloning & indexing)
188
+ await rag.ingest_github("https://github.com/blackeagle686/phoenix-ai.git")
189
+
190
+ # 3. Ingest from Web URL
191
+ await rag.ingest_url("https://example.com/docs/api")
192
+
193
+ # 4. Query with automatic Citations
194
+ answer = await rag.query("How do I extend the cache layer?")
195
+ print(f"AI Answer: {answer}")
196
+ ```
197
+
198
+ ### 🐦‍🔥 Source Attribution
199
+ The SDK now automatically instructs the LLM to cite its sources. When you query the RAG pipeline, the response will often include markers like `[Source: cloud.pdf]` or `[Source: https://example.com]`.
200
+
201
+ ## ⚠️ Local Model Hardware Requirements
202
+ If you plan to use local inference (Ollama or Transformers), please ensure your system meets these specifications:
203
+ - **RAM**: 8GB Minimum (16GB+ recommended).
204
+ - **GPU**: 4GB+ VRAM required for VLM models (using 4-bit quantization).
205
+ - **Disk**: 10GB+ free space for model storage.
206
+
207
+ > [!WARNING]
208
+ > High-resource models may cause system instability on low-RAM or CPU-only devices. The SDK defaults to a safety-first approach and will prompt for confirmation before starting local providers.
209
+
210
+ ## 🐦‍🔥 Dynamic Fallbacks & Native PyTorch
211
+
212
+ phoenix includes a robust "fail-loud and recover gracefully" orchestration architecture for AI providers:
213
+
214
+ ### 1. Interactive Provider Fallbacks
215
+ If your primary provider (e.g. Local) fails to connect or crashes, the SDK's orchestration (`VLMPipeline` / `InsightEngine`) instantly intercepts the failure and prompts you to fallback to the secondary provider (e.g. OpenAI), bypassing pipeline crashes.
216
+
217
+ ### 2. Native PyTorch Singleton Caching (`LocalVLM` & `LocalLLM`)
218
+ No `Ollama` server? No problem! The local providers automatically detect if Hugging Face `transformers` is installed and spin up models natively in your local GPU using an optimized Singleton cache.
219
+ > **Jupyter/Colab Tip**: If you face persistent `Ollama` warnings after installing `transformers`, run `LocalVLM._model_cache.clear()` or `LocalLLM._model_cache.clear()` in your notebook to wipe the previous state and force a PyTorch native reload.
220
+
221
+ ### 3. Automatic 4-Bit Quantization
222
+ To prevent `CUDA Out of Memory` (OOM) errors on smaller GPUs (like Colab T4s), the SDK auto-detects `bitsandbytes` (`pip install bitsandbytes`) and instantly applies `load_in_4bit=True` to shrink massive models (like Qwen2-VL) into your VRAM.
223
+
224
+ ### 4. Resilient RAG PDFs
225
+ The `RAGPipeline.ingest()` method supports PDFs robustly by sequentially testing for parsing libraries: `pypdf`, `pymupdf` (`fitz`), `pdfplumber`, and `PyPDF2`. Simply install whichever you prefer (`pip install pymupdf` is recommended for speed) and it works flawlessly!
226
+
227
+ ## 🐦‍🔥 Advanced Usage: Insight Engine
228
+
229
+ The `InsightEngine` performs full context retrieval, query rewriting, and LLM generation efficiently.
230
+
231
+ ```python
232
+ from phoenix import init_phoenix, get_insight_engine
233
+
234
+ async def insight_demo():
235
+ init_phoenix()
236
+ insight = get_insight_engine()
237
+
238
+ # This invokes: Clean Query -> Vector Search -> Rerank -> LLM Generation
239
+ final_response = await insight.query("How do I extend the cache layer?")
240
+ print(final_response)
241
+ ```
242
+
243
+ ## 🖼️ Quickstart: VLM (Vision)
244
+
245
+ The `VLMPipeline` orchestrates vision tasks with automatic caching and RAG.
246
+
247
+ ```python
248
+ from phoenix import init_phoenix_full, get_vlm_pipeline
249
+
250
+ async def vision_demo():
251
+ await init_phoenix_full()
252
+ vlm = get_vlm_pipeline()
253
+
254
+ # Integrated: Result Caching + RAG context injection
255
+ answer = await vlm.ask("What is in this image?", "image.png", use_rag=True)
256
+ print(answer)
257
+ ```
@@ -0,0 +1,27 @@
1
+ from .main import (
2
+ init_phoenix,
3
+ startup_phoenix,
4
+ init_phoenix_full,
5
+ get_rag_pipeline,
6
+ set_providers,
7
+ get_providers,
8
+ get_insight_engine,
9
+ get_vlm_pipeline,
10
+ get_llm,
11
+ get_memory,
12
+ )
13
+ from .framework.chatbot import ChatBot
14
+
15
+ __all__ = [
16
+ "init_phoenix",
17
+ "startup_phoenix",
18
+ "init_phoenix_full",
19
+ "get_rag_pipeline",
20
+ "set_providers",
21
+ "get_providers",
22
+ "get_insight_engine",
23
+ "get_vlm_pipeline",
24
+ "get_llm",
25
+ "get_memory",
26
+ "ChatBot",
27
+ ]
@@ -0,0 +1,7 @@
1
+ from phoenix.agent.agent import Agent
2
+ from phoenix.agent.loop import AgentLoop
3
+
4
+ __all__ = [
5
+ "Agent",
6
+ "AgentLoop"
7
+ ]
@@ -0,0 +1,81 @@
1
+ import uuid
2
+ from phoenix.llm.openai import OpenAILLM
3
+ from phoenix.memory.hybrid import HybridMemory
4
+ from phoenix.tools.registry import ToolRegistry
5
+ from phoenix.cognition.thinker import Thinker
6
+ from phoenix.cognition.planner import Planner
7
+ from phoenix.cognition.reflector import Reflector
8
+ from phoenix.cognition.analyzer import Analyzer
9
+ from phoenix.execution.actor import Actor
10
+ from phoenix.execution.tool_manager import ToolManager
11
+ from phoenix.agent.loop import AgentLoop
12
+
13
+ class Agent:
14
+ """The main Agent class that integrates LLM, memory, tools, and cognition modules."""
15
+ def __init__(self, llm=None, memory=None, tools=None):
16
+ # Default LLM to OpenAILLM (using LongCat-Flash-Chat by default via its config fallback)
17
+ self.llm = llm if llm is not None else OpenAILLM()
18
+ self.memory = memory if memory is not None else HybridMemory()
19
+ self.tools = tools if tools is not None else ToolRegistry.load_default()
20
+
21
+ # Setup framework
22
+ self.thinker = Thinker(self.llm)
23
+ self.planner = Planner(self.llm, self.tools)
24
+ self.tool_manager = ToolManager(self.tools)
25
+ self.actor = Actor(self.tool_manager)
26
+ self.reflector = Reflector(self.llm)
27
+ self.analyzer = Analyzer(self.llm)
28
+
29
+ self.loop = AgentLoop(
30
+ thinker=self.thinker,
31
+ planner=self.planner,
32
+ actor=self.actor,
33
+ reflector=self.reflector,
34
+ analyzer=self.analyzer
35
+ )
36
+
37
+ def register_tool(self, tool):
38
+ """Helper to register a new tool to the agent's ToolRegistry."""
39
+ self.tools.register(tool)
40
+
41
+ async def run(self, prompt: str, session_id: str = None, max_iterations: int = 15, mode: str = "auto") -> str:
42
+ """
43
+ Run the agent with the given prompt.
44
+ mode can be "auto", "plan", or "fast_ans".
45
+ """
46
+ # Auto-initialize LLM if it's our OpenAILLM and hasn't been initialized
47
+ if hasattr(self.llm, "client") and self.llm.client is None:
48
+ if hasattr(self.llm, "init"):
49
+ await self.llm.init()
50
+
51
+ if session_id is None:
52
+ session_id = str(uuid.uuid4())
53
+
54
+ # Add user prompt to memory
55
+ await self.memory.add_interaction(session_id, "user", prompt)
56
+
57
+ # Decide mode if auto
58
+ actual_mode = mode
59
+ if mode == "auto":
60
+ classification_prompt = (
61
+ f"Analyze the following user prompt and decide if it requires using tools and multi-step planning (like writing files, searching the web, or complex logic), "
62
+ f"or if it is a simple question that can be answered immediately.\n\n"
63
+ f"Prompt: {prompt}\n\n"
64
+ f"Respond with exactly one word: 'PLAN' or 'FAST'."
65
+ )
66
+ classification = await self.llm.generate(classification_prompt, session_id=None)
67
+ if "PLAN" in classification.upper():
68
+ actual_mode = "plan"
69
+ else:
70
+ actual_mode = "fast_ans"
71
+
72
+ if actual_mode == "fast_ans":
73
+ # Fast answer mode: bypass the agent loop and just use the LLM directly with memory context
74
+ context = await self.memory.get_full_context(session_id, query=prompt)
75
+ fast_prompt = f"Context:\n{context}\n\nUser: {prompt}\nAnswer directly:"
76
+ fast_answer = await self.llm.generate(fast_prompt, session_id=None)
77
+ await self.memory.add_interaction(session_id, "assistant", fast_answer)
78
+ return fast_answer
79
+ else:
80
+ # Start execution loop
81
+ return await self.loop.run(prompt, self.memory, session_id, max_iterations=max_iterations)