This release is a pre-release and may not be stable for production use.
portfolio-agent
portfolio-agent is an open-source Python toolkit for turning a person's or team's documents, repositories, and web content into a citable, persona-aware assistant.
The repository is intentionally standardized around one supported path:
- ingest content with
PortfolioAgent - index it into the local
FAISSVectorStore - query it through the built-in persona-grounded
RAGPipeline
What Is Supported
- Python SDK via
PortfolioAgent - Local FAISS indexing
- File ingestion for text/markdown/html/json/pdf
- GitHub and website ingestion through the SDK
- Querying with citations and lightweight session memory
- Optional FastAPI wrapper via
create_app(...)
What Is Not the Supported Surface
- the old
build_graph()entrypoint - placeholder enterprise/platform claims
- legacy example scripts outside the portfolio demo
- unfinished HTTP endpoints for streaming, batch orchestration, admin, or security tooling
Public Release Scope
This repository is preparing for a narrow, truthful first public tag.
Release-ready expectations:
- install from source or package
- run the smoke/manual path
- run the smoke benchmark
- inspect source-backed answers and benchmark output
Not promised in this release:
- broad production guarantees
- exhaustive benchmark coverage for every ingestion format
- automatic validation of every optional runtime in every environment
Installation
When published as a package:
pip install portfolio-agent
From a fresh clone:
poetry install
From a locally built artifact:
poetry build
pip install dist/portfolio_agent-*.whl
For local embeddings, the package defaults to Hugging Face sentence-transformers. The first run may download the configured model.
Manual Verification
The fastest supported end-to-end check from a fresh clone is:
python scripts/manual_e2e.py --mode smoke
For the actual configured runtime path:
python scripts/manual_e2e.py --mode settings
See docs/MANUAL_E2E.md for the full SDK, CLI, and API verification flow. If your environment can load the real local embedding runtime, you can also run the opt-in integration check documented there.
Evaluation
The repo also includes a small benchmark for retrieval, grounding, abstention, and source-label quality on the canonical SDK path:
python scripts/run_evaluation.py --mode smoke
For the real configured runtime:
python scripts/run_evaluation.py --mode settings
See docs/EVALUATION.md for what the benchmark covers and what it does not.
Release Validation
For a maintainer/reviewer release pass:
python scripts/release_check.py
For a heavier clean-environment review of the configured embedding runtime:
python scripts/release_check.py --include-settings
See docs/RELEASE_CHECKLIST.md for the minimum release gate and review notes. The built-artifact dry run validates the wheel in a temporary virtual environment using available local site packages; it is meant to prove package usability, not to simulate a full online dependency-resolution install. For the end-to-end maintainer handoff, see docs/RELEASE_CANDIDATE.md.
Versioning
This project is currently using a pragmatic 0.x release shape:
- the canonical
PortfolioAgentSDK path is the supported contract - internals and heuristics may still evolve between minor releases
- release notes and changelog entries should be read as the source of truth for what changed
Current release candidate: 0.3.0rc1
See CHANGELOG.md for release notes.
Quick Start
from portfolio_agent import PortfolioAgent
agent = PortfolioAgent.from_settings()
agent.add_text(
"""
Jane Doe is a backend engineer who works with Python, FastAPI, and retrieval systems.
She has built developer tooling, API platforms, and AI product prototypes.
""",
source="profile.txt",
document_type="txt",
)
result = agent.query("What does Jane work on?")
print(result.response)
print(result.sources)
Ingest a File
from portfolio_agent import PortfolioAgent
agent = PortfolioAgent.from_settings()
agent.add_file("sample_docs/portfolio.txt")
result = agent.query("Summarize the indexed portfolio")
print(result.response)
Ingest a GitHub Repo or Website
from portfolio_agent import PortfolioAgent
agent = PortfolioAgent.from_settings()
agent.add_github_repository("https://github.com/example/project")
agent.add_website("https://example.com")
FastAPI App
from portfolio_agent import PortfolioAgent, create_app
agent = PortfolioAgent.from_settings()
app = create_app(agent=agent)
Supported API endpoints:
GET /api/v1/healthPOST /api/v1/queryPOST /api/v1/documentsPOST /api/v1/documents/file
CLI
The package exposes a portfolio-agent CLI:
portfolio-agent --add-file sample_docs/portfolio.txt --query "What are the key skills?"
portfolio-agent --interactive
portfolio-agent --serve
If you are validating a fresh clone and want the quickest repeatable check, use python scripts/manual_e2e.py --mode smoke before using the heavier local-embedding runtime.
Configuration
Key environment variables:
EMBEDDING_PROVIDER=hf
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
EMBEDDING_BATCH_SIZE=16
# EMBEDDING_DEVICE=cpu
FAISS_INDEX_PATH=./faiss_index
REDACT_PII=true
TOP_K_RETRIEVAL=5
If you want OpenAI embeddings instead of local embeddings:
EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-3-small
OPENAI_API_KEY=your-key
Canonical Architecture
Source -> Ingestor -> Chunker -> Embedder -> FAISSVectorStore
|
Query -> RouterAgent -> RetrieverAgent -> RerankerAgent -> PersonaAgent -> Response
|
MemoryManager
See docs/QUICKSTART.md for a slightly more detailed walkthrough.
Metadata
Release files for portfolio-agent 0.3.0rc1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| portfolio_agent-0.3.0rc1.tar.gz | 116.8 kB | Without provenance | Details for portfolio_agent-0.3.0rc1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| portfolio_agent-0.3.0rc1-py3-none-any.whl | Python 3 | none | any | Details for portfolio_agent-0.3.0rc1-py3-none-any.whl |
Total release size: 271.4 kB
Release files / portfolio_agent-0.3.0rc1.tar.gz
| Download URL | portfolio_agent-0.3.0rc1.tar.gz |
|---|---|
| Size | 116.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0ae8b8f556d39075578c5f7a3a48b085e73e07219c1845316189754cb20fdd33
|
|
BLAKE2b-256 checksum How to use checksums |
ed393e98fcace431e1fca7896b193ad955b558b19adcf2d2cf1b4757bf78c192
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.4 CPython/3.13.5 Darwin/25.4.0
|
Release files / portfolio_agent-0.3.0rc1-py3-none-any.whl
| Download URL | portfolio_agent-0.3.0rc1-py3-none-any.whl |
|---|---|
| Size | 154.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
935977b1695769d597f0dc0198ca3f4a74c540908615b3d9874b37755c6ce02e
|
|
BLAKE2b-256 checksum How to use checksums |
64109ce18add17b87869f0598ab1f2fbebf62663b145a9950db887d06434cbee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.4 CPython/3.13.5 Darwin/25.4.0
|
Security for portfolio-agent 0.3.0rc1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.